Shareware Overload Trio 2

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Overload Trio 2 / Shareware Overload Trio Volume 2 (Chestnut CD-ROM).ISO / dir36 / skey40.zip / BATUTIL.DOC next >

Wrap

Text File | 1993-01-07 | 387KB | 8,877 lines

BBBBBB AAA TTTTTT UU UU TTTTTT IIII LLLL (tm) BB BBB AA AA T TT T UU UU T TT T II LL BB BB AA AA TT UU UU TT II LL BBBBB AA AA TT UU UU TT II LL BB BB AAAAAAA TT UU UU TT II LL BB BBB AA AA TT UU UU TT II LL LL BBBBBB AA AA TTTT UUUU TTTT IIII LLLLLLL Version 4.0 CTRLALT Associates (R) _______ ____|__ | (R) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER TABLE OF CONTENTS Chapter I:OVERVIEW........................................3 I.1 Shareware Considerations...........................3 I.2 What BATUTIL does..................................6 I.3 Help and Verbose Modes and European Dates..........9 I.4 New in Version 4.0................................11 I.5 Basic Syntax......................................13 I.6 Setting BATUTIL options from the environment......16 I.7 Reading commands from a file......................17 I.8 BATUTIL's line editor.............................19 I.9 BUSIC - a first look..............................20 I.10 String manipulation, arithmetic and date arithmetic..........................22 I.11 Control Break handling...........................23 Chapter II:SYSTEM INFORMATION............................25 II.1 Overview.........................................25 II.2 Time.............................................26 II.3 Operating System and Memory Information..........26 II.4 Console Information..............................29 II.5 Hardware Information.............................31 II.6 File Information.................................32 II.7 The RUn Command..................................34 II.8 TOdayfile and MAkefile...........................37 II.9 The ERrorlevel command...........................38 Chapter III: DISPLAY TOOLS...............................39 III.1 Overview........................................39 III.2 Metastring Translation..........................39 III.3 BATUTIL's ECho Command..........................43 III.4 The BOx Command.................................45 III.5 The PRetty Command..............................46 III.6 Bigecho.........................................47 III.7 Getting Echo/Pretty Input from a File...........50 III.8 Cursor Position and Hiding the Cursor...........50 III.9 The STdout Command..............................51 III.10 Sounds.........................................52 Chapter IV:USER INPUT....................................54 IV.1 Menu Basics......................................54 IV.2 Getting a Menu from a File.......................55 IV.3 Menu Options.....................................56 IV.4 GEtkey Basics....................................58 IV.5 GEtkey Options...................................60 IV.6 AScii, SCanread..................................63 IV.7 USername/Password Checking.......................63 IV.8 Parameter Matching...............................64 IV.9 Querying the Lock Status.........................65 Chapter V:ENVIRONMENTAL CONTROL..........................67 V.1 Environmental Impact Statement....................67 V.2 Environment Reports...............................69 V.3 SEt Basics........................................70 V.4 Internal Variables and Hacker Mode................71 V.5 Getting User Strings into the Environment.........72 V.6 Using the File Pick List..........................75 V.7 Saving and Loading the Environment to a File......76 V.8 Batch File Path Control...........................78 V.9 Direct Editing of the Path........................79 V.10 Direct Editing of the Environment................80 Chapter VI:BUSIC.........................................81 VI.1 Internal Variables...............................81 VI.2 String Manipulation..............................82 VI.3 Arithmetic.......................................84 VI.4 Date Arithmetic..................................86 VI.5 Reading from and Writing to Files................88 VI.6 BUSIC Summary and Overview.......................90 VI.7 LABELS, GOTO and CALL............................92 VI.8..IF...THEN...ELSE and CASE.......................94 VI.9..FOR, REPEAT and WHILE...........................96 VI.10 FOR Loops with Lists, Files and Directories.....98 V.11 Internal Structure...............................99 VI.12 Trace Mode.....................................102 VI.13 Hacker Mode....................................105 Chapter VII:TIPS AND EXAMPLES...........................106 VII.1 General tips...................................106 VII.2 Returning to your Initial Directory............106 VII.3 Using BATUTIL in your autoexec.bat.............107 VII.4 A Clean Sweep..................................108 VII.5 Directory Lister with Smart Wildcards..........109 VII.6 A Two Year Olds' Delight.......................109 VII.7 Sample Batch Files.............................110 Chapter VIII:COMMAND REFERENCE..........................112 Chapter IX:ERROR MESSAGES...............................154 IX.1 Fatal Errors....................................154 IX.2 List of Error Codes.............................154 IX.3 Explanation of Error Codes......................155 Chapter I:OVERVIEW I.1 Shareware Considerations BATUTIL is a program included in the STACKEY package by CTRLALT Associates. If you are a shareware evaluator, we appreciate your taking the time to try out this program. We'd like you to skim this section before going to the next that actually tells you what BATUTIL does. Full details as to warranty and license terms can be found in the STACKEY documentation. BATUTIL is shareware. You have a 30 day trial period from the time that you first use the program to see if it meets your needs. If you continue to use it after that time you are required to pay a license fee not as a contribution but because you are getting use from our program. Shareware is dedicated to the idea that users are best served by a chance to fully try out something as complex and individualistic as software before they buy it and that authors are served by an ethic that encourages wide copying for trial runs. But in order for the system to work you need to respect the trust that we show in you and register if you continue to use our program. BATUTIL can only be registered as part of the STACKEY package. License fees are as follows: License to BATUTIL/STACKEY with printed documentation $49 Shipping and handling is extra: $4 in the US and Canada and $13 elsewhere to cover air shipping outside the United States. Registered users of Version 1.0 may upgrade for $29 plus S&H. We have special registration arrangements you can use if you choose in Australia and the United Kingdom - these are also described in the STACKEY docs. All licensing will get you the latest version on disk. The printed documentation is essentially identical to the documentation on disk. Basically, you cannot distribute BATUTIL as part of a package of goods or services for which you charge a fee without one of the following: - a separate license for each person receiving the program - the right to distribute this program as shareware for a fee - an arrangement with Ctrlalt Associates Details are in the STACKEY documentation and in the vendor.doc file. These restriction do NOT apply to copies you give for NO fee to others for shareware evaluation. Chapter I:OVERVIEW Page 3 Documentation for BATUTIL, Version 4.0 You may register by phoning or writing Advanced Support Group 11900 Grant Place Des Peres, MO 63131 1(800)788-0787 1(314)965-5630 FAX 1(314)966-1833 Mastercard/Visa/Discover/AmEx and purchase orders from approved institutions are accepted. This is not the number for support (see below). Payment of the license fee gives you the right to use any version of BATUTIL with a major version number of 4. If there is a Version 5, an update fee may be required. In addition to the thirty day trial period, you may return the disks (and printed documentation) for a full refund if you are not totally satisfied for a period of 90 days after initial payment. You have the choice of one of two license terms: "use like a book" OR a single user license. The former allows you to place copies of this software on as many machines as you wish so long as there is NO CHANCE that more than one copy of BATUTIL will be loaded into any of the machine's memories at one time. The latter allows you to place copies on all machines for which YOU are the principal user even if there is a chance that OCCASIONALLY more than one copy is in use (for example, if you use BATUTIL on a office machine while a family member might OCCASIONALLY use a copy on a home machine at the same time). The 800 number is for orders only. Registered users may obtain support in three ways: by writing to CTRLALT Associates or via Compuserve and via a 900 telephone number. Details can be found in the STACKEY documentation. In particular, Ctrlalt Associates have a section (Section 12) on Compuserve's PCVENA forum - leave messages there for 76004,1664. Compuserve and mail support are free of charges other than postage or Compuserve connect time. There is a $2/minute charge for calling the 900 number (initial 24 secs are free). This support is offered by Advanced Support Group in cooperation with Ctrlalt Associates. (Note: the 800 is for orders/registration only and cannot be used for support.) If you like the program, please give it to your friends, place it on bulletin boards and otherwise spread it around. We explicitly allow TRIAL use of it privately and in a commercial Chapter I:OVERVIEW Page 4 Documentation for BATUTIL, Version 4.0 environment. You may give it away, but you may not charge for it or include it with commercial software without our written permission. An exception is made for user groups and shareware software distributors who are approved shareware distributors of the Association of Shareware Professionals, an organization to which both authors of BATUTIL belong. Details on these restrictions, ASP and information on the ASP Ombudsman can be found in the STACKEY documentation. The following names may be trademarked: Turbo Pascal, Turbo Professional, Turbo Plus, Pianoman, Desqview, Omniview, Software Carousel, Techhelp, Flambeaux Software, Intel, Microsoft, Lotus, 123, List, Ultravision, 4DOS, Qemm, 386Max, Eemram. BATUTIL, and STACKEY are trademarks of and Ctrlalt is a registered trademark of Ctrlalt Associates. BATUTIL was written in Turbo Pascal. Extensive use was made of the routines in Object Professional published by Turbo Power Software and of Turbo Plus published by Nostradamus. The tunes used in the sound command were developed with Pianoman, a shareware program by Neil Rubinking. We would like to thank Quarterdeck Office Systems for providing information on the programming interface to Desqview, and Scott Bussinger and Kim Kokkonen for comments on our Ctrl-Break handler. BATUTIL is warranted for no particular purpose. While we have tried to make the program bug free, no software can be guaranteed to be free of bugs. Due to the complex nature of computer software CTRLALT ASSOCIATES does not warrant that the licensed Software is completely error-free, will operate without interruption, or is compatible with all equipment and software configurations. Repair, replacement or refund, at the option of the CTRLALT ASSOCIATES, is the exclusive remedy of the customer, in the event of a defect. By using this program, you accept it AS IS and agree that we will NOT be held responsible for any damages including but not limited to consequential damages or loss of data. This includes damages caused by problems of which CTRLALT Associates is already aware. We will attempt to correct any bug which is pointed out to us. Registered users are entitled to use bug fixes while still numbered 4.xx. We do not intend to support Version 4.xx once a Version 5.xx is available and you may need to pay an upgrade fee to a new version if there are any bug fixes made once Version 5.xx is available. We will endeavour to continue to Chapter I:OVERVIEW Page 5 Documentation for BATUTIL, Version 4.0 support registered users of Version 1.0 who choose not to upgrade but will not attempt to fix any problems in that version but instead fix the current version. You may ask for a full refund of your registration for a period up to 90 days after you register but only if you return the program package sent registered users and agree to destroy any copies of BATUTIL and STACKEY in your possession and cease using the programs. While we have attempted to make this documentation as clear as possible, we cannot guarantee that there will not be misunderstanding or user error. We specifically exclude any warranties, EXPRESS OR IMPLIED, including the IMPLIED WARRANTIES OF MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SOME STATES DO NOT ALLOW THE IMPLIED WARRANTIES TO BE EXCLUDED. CONSULT A LAWYER TO SEE WHETHER OR NOT THE ABOVE EXCLUSIONS APPLY TO YOU IN YOUR STATE. I.2 What BATUTIL does BATUTIL is a program with two purposes: to give you power inside your batch files and to give you more control over the DOS environment. To get a feel for the program, please run budemo which is included with the distribution files. Included in the information that you can get returned in either the DOS errorlevel, stored in BATUTIL's internal variables or an environmental variable are - current time, date, day of the week - total amount and amount free of disk space, memory and EMS - CPU type and type of coprocessor if present - whether a file exists not only in the current directory but on the DOS path and if it exists on the DOS path, the actual directory can be returned in another environmental variable - whether a file has today's date or not - whether one of two files is older than another - you can parse a filespec into individual components - you can do arithmetic on integers and dates - you can manipulate strings including case change and centering - whether Desqview or Carousel is running and, if, so which partition you are in; whether Windows is running underneath you Chapter I:OVERVIEW Page 6 Documentation for BATUTIL, Version 4.0 Some of these options may not seem so useful at first sight, but, for example, whether a file has today's date or not can be used to make a routine that will only get run once per day. Chapter VII will explain sample uses of BATUTIL. Central to the design of BATUTIL is the notion of "high level" language. There are much more sophisticated batch languages available and in them one can write menus at least as involved as are available in BATUTIL's MENU command. But doing so requires you to write a little program in the batch language while MENU is a built in command of BATUTIL. If you want to, BATUTIL comes with a full featured language dubbed BUSIC including, IF..THEN..ELSE, CASE, WHILE, REPEAT and GOTO all of which can be used in the style of DOS batch languages. In addition to getting information from the operating system, you can pass information to and get information from the user. BATUTIL gives you considerable control over displaying information including the possibility of turning the cursor on and off and displaying messages in various colors. And BATUTIL understands the metastrings that STACKEY does so you can easily display data like today's date in English. As for user input it can be obtained in various forms - There is a getkey routine that lets you list a set of keys using STACKEY syntax and get which key in the list the user has hit - whether a lock key is currently pressed - with some simple commands, you can popup an elegant menu for the user to pick from and have the choice returned in the errorlevel - You can have the user input a string and get it stored in the environment - You can have the user type in a user name or password and see whether it matches a predetermined list and have which item is matched reported in the errorlevel - You can popup a filename list for the user to choose from and have the answer stored in the environment BATUTIL also gives you considerable control over the DOS environment. It is able to do this by using undocumented features of the operating system. As always, such features should be used with care. PLEASE READ CAREFULLY THE WARNING AT THE START OF CHAPTER V CONCERNING USING UNDOCUMENTED FEATURES TO ACCESS THE DOS ENVIRONMENT. BATUTIL's environmental control has been tested with Chapter I:OVERVIEW Page 7 Documentation for BATUTIL, Version 4.0 PCDOS Version 2.0, 2.1, 3.0, 3.1, 3.2, 3.3, 4.0, 5.0 and some flavors of MSDOS. Besides being able to place information into the environment via user input, BATUTIL will - display more information about the environment than the SET command - allow you to put strings in the environment up to a length of 255 characters rather than the 127 character maximum that DOS allows. In particular, with BATUTIL, your PATH string can be up to 250 characters rather than the 122 characters that you can enter with DOS. (While DOS doesn't care about long paths, you may have an application program that does and crashes if it finds a path over 127 bytes). - allow simple commands to add a directory to your PATH without inadvertently adding one already there and allow deletion of a directory from your PATH - allow full screen editing of your environment and PATH. - allow you to save the environment to a file, to load or merge a file into the environment and to kill the environment (use with care). The files in the BATUTIL package are as follows: BATUTIL.EXE The basic program. The only file required to use BATUTIL BATUTIL.HLP Online help called by BATUTIL if you use BATUTIL ? or BATUTIL !; SEE BELOW BATUTIL.DOC Documentation in electronic form BUDEMO.BAT Sample batch file which will call the other sample batch files COLORDEM.BAT Sample batch file shows color capability EQUIP.BAT Sample batch file shows ability to read hardware INPUTDEM.BAT Sample batch file shows ability to get input from the user MENUDEMO.BAT Sample batch file shows BATUTIL's menu making capability SHOWDEMO.BAT Sample batch file shows display options including big characters and metastrings SOUNDEMO.BAT Sample batch file with BATUTIL's 20 sounds/tunes LANGDEMO.BAT Sample batch file demonstrating the new language features of BATUTIL 4.0 WHATEL.EXE Program described in Section II.7 to determine errorlevel and timing for some command Chapter I:OVERVIEW Page 8 Documentation for BATUTIL, Version 4.0 Because of our desire to keep the basic files on a single disk and to keep download time low, we are encouraging distribution of a 'small' shareware version without the BATUTIL.HLP file. If you got a version without this file and want it for evaluation, it can be downloaded from our support section of Compuserve as BUHELP.EXE (Section 12 of PCVENA) or gotten from many disk vendors including PBS (1-800-426-3475). If you upload this program to a BBS, please keep BATUTIL.HLP as a separate file. BATUTIL, its help file and documentation are copyright 1988- 91 by Barry Simon and Richard Wilson, all rights reserved. If you obtain BATUTIL/STACKEY from Advanced Support Group, directions for installing the programs can be found in the STACKEY docs and with a readme.com file. ******************************************************************* IMPORTANT NOTES Users of 4DOS Version 2.x; please read Section V.1 before calling for technical support. See Section I.4 for items in Version 1 not carried over to Version 4.x. ******************************************************************* I.3 Help and Verbose Modes and European Dates You can obtain interactive help for BATUTIL by typing in batutil ? or batutil ! at the DOS prompt. To obtain help, the binary file BATUTIL.HLP must be available in the current directory or the directory where BATUTIL is loaded or in your path. BATUTIL looks for the first two non-blank characters following the ? (or !) and if they are a valid BATUTIL command, you will be immediately sent to the help for that command; otherwise, the main help menu will be displayed. For example batutil ? SE would display help for BATUTIL's SET command as would batutil ?see the beautiful program BATUTIL ? displays the menu oriented help with various special effects. If these effects and the slightly longer time Chapter I:OVERVIEW Page 9 Documentation for BATUTIL, Version 4.0 they take bother you, batutil ! will display help without the special fades for displaying material. The help program uses color attributes on a graphics monitor. If you have a two color graphics monitor (such as on a laptop) or the colors are hard to see, the help program will use monochrome attributes if you use SET BU!=bw in your autoexec.bat file or at the DOS command line before running BATUTIL. Note that on a true monochrome adapter (IBM MDA or Hercules monographics card), the help program will not use color attributes whether you use that set command or not. Normally, BATUTIL exits when there is an error and sets the errorlevel between 200 and 253; see the discussion in Chapter IX. There are three levels of visual error reporting that you can have turned on. For debugging purposes the default is a verbose mode where BATUTIL will explain why it is exiting. For batch files you distribute you may want to have verbose mode turned off and instead use a Quiet mode where no messages are displayed. To turn on this quiet mode, just make the first non blank character in the command line the letter Q. Thus, batutil {} would display an error message while batutil Q {} would exit without any message. For distributed batch files made with BATUTIL, you may want to turn on quiet mode using an environmental variable as described in Section I.5. Command line mode takes precedence over any mode set in the environment and, in particular, you can override the mode set in the environment and restore to the default Verbose mode by making V the first letter on the command line after "BATUTIL". Chapter IX has a complete list of error codes with an explanation of each. The online help main menu has an option to list all error numbers and their meaning. In batch files, the error message may disappear too fast for you to see. In addition to Verbose mode, BATUTIL has a Pause mode which shows the error message and waits for a key before exiting. Pause mode is set with the letter P. To see the information which BATUTIL is placing in the environment while testing out what a command will do the following Chapter I:OVERVIEW Page 10 Documentation for BATUTIL, Version 4.0 one line batch file (or an equivalent CED synonym) is useful: batutil %1 %2 %3 %4 %5 %6 %7 %8 %9 {EC $x(rc)} The final command echoes the current value of the environmental variable RC to the screen. There is an additional special parameter you can use at the start of the command line - E for European. It will change to European date conventions so, while batutil {ec $E} would echo December 19, 1991 the command batutil E {ec $E} would echo 19 December 1991 The E command effects the following: the meaning of $d, $E and the translation used for dates, for example batutil {ec $E(1/2/91)} returns January 2, 1991 while batutil E {ec $E(1/2/91)} returns 1 February 1991 since 1/2/91 is also translated using European conventions. I.4 New in Version 4.0 Version 1.0 was released bundled with Stackey 3.0 and this numbering caused some confusion so, with this upgrade, we have upped the version number of BATUTIL all the way to 4.0 to make the numbers the same. The most significant differences in this new version are the addition of a built in language described further in Sections I.9, I.10 and Chapter VI. For this language to work effectively, we needed to remove the restriction of a single 127 character command line and it is now possible to read commands in from a file as described in Section I.7. As a bonus, you need not load BATUTIL many times and that increases the speed of command processing by a considerable amount. Chapter I:OVERVIEW Page 11 Documentation for BATUTIL, Version 4.0 This may mean that you'd like to use BATUTIL's RUn command to run a program from a BATUTIL batch file without exiting BATUTIL. In Version 1.0, BATUTIL took over 200K when you used RUn limiting it for these purposes. With this version, BATUTIL will swap itself to hard disk or EMS memory leaving a core of about 11K in conventional RAM. About 300K of disk space or EMS is required. By default EMS is used if available but you can tell BATUTIL to use disk. This swapping mechanism RUn command will not work on systems with floppy only and no EMS so you'll have to use the non-swapping mode (set up by placing BUSWAP=! in your environment) Included in the language support are: - Labels and Goto - Calling subroutines - IF..THEN..ELSE and CASE - WHILE and REPEAT - 32 internal variables as well as the use of the DOS environment for storing information - FOR loops using an internal loop variable - FOR loops using a list - FOR loops using file wildcards like DOS batch files - FOR loops varying through a directory tree - An interactive trace mode - String manipulation including change of case, length, formatting, searching, and word count - Integer arithmetic with four functions, mod and power - Date manipulation including date arithmetic - Reading and writing to files with optional metastring translation - reading from the screen - Memory peeks and pokes - I/O port peeks and pokes Other new features include - reading the number of file handles and DOS buffers - determining if BATUTIL is running in a Windows DOS box - determining if Norton's NDOS is running - determining if SHARE is loaded - determining the value of last drive - A command to display text boxes with choice of frame characters and shadows - mouse support in the $F routines - a $N metastring like $Q but with input restricted to numbers and a test to see if a string is a number Chapter I:OVERVIEW Page 12 Documentation for BATUTIL, Version 4.0 between allowed maximum and minimum values - the #I command will now identify 486 CPUs - super metastrings to force commands that do not do metastring translation on their parameters to do such translation after all - menu can now be set to timeout after a fixed time - support for European dates - a password mode for entry of strings which are masked There have been the following changes from Version 1.0: - Support for Omniview has been dropped - SOund number 1 has changed slightly - HAltif still works for compatibility but is not documented because it is better to use an IF ... THEN GOTO HALT command - The method for identifying second monitors has changed to something that may not work as well on older machines but which works on systems with VGA and later just using BIOS calls - BATUTIL will no longer properly identify 287 chips in a system (rather unusual) where a 386 and 287 are present I.5 Basic Syntax Command: REmark You give BATUTIL a series of commands on the command line or read them in from a file. There are about 130 different commands - lest that overwhelm you, we note that many are just giving different pieces of hardware information which you'll rarely want and even the most complex idea (menus) are controlled by one basic command and fewer than ten commands which effect options like whether the menu explodes. Chapter VIII is a detailed alphabetical command reference. When you invoke BATUTIL's help, one option is an alphabetical list of commands which will give you a panel with syntax and parameters for each. The basic syntax is batutil {command1} {command2} ... Each command is placed inside braces {} (or square brackets []; see below). On the command lines, the braces are critical - it doesn't matter whether you have spaces between } and the next { or not. For Chapter I:OVERVIEW Page 13 Documentation for BATUTIL, Version 4.0 reading commands from a file, braces are not needed if commands are on distinct lines, see Section I.7. Commands are broken into two classes - normal commands and BUSIC language commands. All normal commands have a two element minimal truncation. That is all normal commands are distinguished already in the first two symbols and any substring of the command that has at least two letters will work. For example, the basic command to get a report on the environment is batutil {envrep} The minimal truncation for that is EN so we'll often write ENvrep to emphasize this. Thus batutil {en} or batutil {envr} would work just as well as the full name. The basic commands are not case sensitive so {EN} or {En} or even {eNvRe} would do the same thing as {envrep}. While to emphasize minimal truncation, we'll write ENvrep, please bear in mind that BATUTIL commands are NOT case sensitive although $ metastrings ARE. The BUSIC language commands: IF, WHILE, CALL, FOR, FORDIR, REPEAT, CASE, END, RET, ENDCASE, UNTIL, and BEGIN cannot be abbreviated although they are not case sensitive. In addition to avoid accidents the HACKER + command cannot be abbreviated but must be used in full. In addition, much of the metastring translation acts as if it were commands - that is there is little difference between the HOur command which sets the errorlevel to the current hour and $H which returns the current hour in a string so that {HO} and {ER $H} are equivalent. Roughly fifty of the commands return to the user (i.e. you as a batch file writer) a number from 0 to 199. If the command in question appears inside {} then that number is stored in the environmental variable RC (short for "return code"; environmental variable are discussed at the start of Chapter V). If the command appears in [], then BATUTIL will exit without running the rest of the command line and place this integer in the DOS errorlevel where you can test it with commands like if errorlevel .... Chapter I:OVERVIEW Page 14 Documentation for BATUTIL, Version 4.0 (see Chapter VII). IF THE LAST COMMAND ON THE LINE RETURNS AN INTEGER AND IT IS PLACED IN {}, THEN the integer is both placed in the real environment and placed in the error level. For example, DRive reports the current drive with 0=A, 1=B, etc. If the current drive is D, then batutil .... [DR] will set the errorlevel to 3, while batutil .....{DR} {echo hi there!} would set an environmental variable RC to 3 and then echo "hi there!". Thus if you ran the SET command after BATUTIL, you'd find the line RC=3 on your screen. Every time a command would set the environmental variable RC, it also sets the internal variable $r accessible via metastring translation. If you wish to run BATUTIL in a mode where it doesn't use the user's environment, the {RC $} command will tell BATUTIL to only use $r and not set an environmental RC variable. Some commands will take optional parameters which also appear inside the braces for that command. Thus @Disk gives the free disk space. If no parameter is specified, then the current default drive will be used. Otherwise you can specify a drive as in batutil {@D C} BATUTIL will object to incorrect syntax so if you tried batutil {@D 3} then BATUTIL will exit (with an appropriate message if Verbose mode is on). You can separate the command from the first parameter by any of the following: <space>,<comma>,= or : Rules of separation of multiple parameters for those few commands which accept multiple parameters depend on the commands. Some commands do explicit metastring translation of their parameters and others do not. For any non-BUSIC command, if you place the parameters inside $!(...), then metastring translation will take place before the parameters are passed on. Thus even though NUmberfiles does not normally do metastring translation, the command {NU $!(...)} would first do metastring translation on ... and then process the command {NU ---} where --- is the metastring translation of ... This supermetastring Chapter I:OVERVIEW Page 15 Documentation for BATUTIL, Version 4.0 translation even allows $Q, $N and $F file input. Before doing anything BATUTIL scans the command line and makes sure that every command is a proper one for this version of BATUTIL. If not, it will exit. Otherwise, it will execute the commands one at a time. It does not check for parameter syntax until that command is reached. Thus {@D 3} will halt BATUTIL when reached but earlier commands will already have run. You may place remarks in the BATUTIL command line by enclosing them inside {} with the REmark command as in batutil {AT 4F}{CL}{REM clears the screen in red!} I.6 Setting BATUTIL options from the environment You can effect BATUTIL's behavior with five environmental variables: BU@, BU^, B4$, CUR and BUSWAP. These are set with DOS set command or BATUTIL's SEt command. When BATUTIL loads, before reading the rest of its command line, it looks for an environmental string of the form BU@=string and it first reads that string as if it were a command line and places the commands in it to be processed first. This is intended primarily to allow you to change the built in default options to some other value. For example, to turn off beeps and change the default on GEtkey from flushing the keyboard to not, you'd use: BU@={NB}{NF} This option is useful if you want to permanently turn on pause mode or European date mode; you'd use BU@=P E {NB} if you wanted to also turn beeps off. Since BATUTIL looks in the environment, you place the information that you want there using the DOS SET command (or BATUTIL's SET command if you want!); for example, you might place a line set BU@=P E {NB} in your autoexec.bat file. It is important to place NO spaces between BU@ and the =. Spaces after the = are unimportant. Chapter I:OVERVIEW Page 16 Documentation for BATUTIL, Version 4.0 There are four other environmental variables of interest. One is the variable B4$. At the end of the commands to edit your path and the environment ({PAthedit} and {EDitenv}) and after using help, a screen will appear reminding you of the fact that BATUTIL is shareware limited to a 30 day trial period. You can suppress this screen by placing B4$=I paid in your environment. Obviously, having told you the secret, you can do it even if you haven't paid - let your conscience be your guide. The variable BU^ can be used to turn off ^Break handling; see Section I.11. BATUTIL's RUn command swaps to hard disk or EMS. You can control where swapping takes place with the BUSWAP variable. This is discussed in Section II.7. The final environmental string that BATUTIL pays attention to is CUR (for CURSOR). It looks for two possibilities: CUR=no Normally, BATUTIL restores the cursor when exiting, even if you have turned it off with the {CU -} command of Section III.7 If this string is present the cursor is not turned back on but its state is not changed. The other possibility is CUR=off When starting or exiting the program, BATUTIL will turn the cursor off if this string is found at that point. All other values of CUR are ignored. I.7 Reading commands from a file Commands: FCommand, INclude Four commands are able to read information in from a file. The FCommand command which is equivalent to the INclude command reads new commands from a file. The ECho command displays text on the screen in colors you set before the echo command; PRetty displays text in colors that you can adjust as part of the string displayed and MEnu displays a user defined menu. The analogous file reading commands are FEcho, FPretty and FMenu. Each command takes two parameters: the first is a filename and is required, the second a label name which is optional. If the filename is given without a drive or directory, then it is searched for first in the current directory. If not found by BATUTIL, BATUTIL will attempt to add an extension of bat and look again. Then the same search is made in the directory that BATUTIL Chapter I:OVERVIEW Page 17 Documentation for BATUTIL, Version 4.0 was loaded from (under DOS 3.0 and later) and finally in the DOS path. If still not found, BATUTIL exits and an error message is issued. If no label name is given, then BATUTIL will start reading and processing the file from its beginning. If a label is given, BATUTIL reads the file from the beginning but searches until it find a line beginning with :label (leading spaces before the : are ignored and labels are NOT case sensitive). For example batutil {FE foobar.txt hi} would look a file named foobar.txt and then search for a line starting with :hi If the label is not found, then BATUTIL exits with an error message. Otherwise the file is processed one line at a time until the next line beginning with a : is located. Lines whose first symbol is a ; are ignored (i.e. treated as remarks). You can combine batch file labels and BATUTIL's labels to keep the extra lines to display in the batch file itself. For example, the following could be at the start of a batch file: goto codestart :echostart This line will be echoed and this will appear on the next line ;but this line is a remark The last line doesn't have an explicit CR added :codestart batutil {FEcho %0 echostart} Because BATUTIL will add .bat to a filename if it cannot find the file without that, the %0 will be properly interpreted (unless you happen to have a file with the same name as the batch file and no extension). FEcho, FMenu, and FPretty are limited to reading in 25 or fewer lines. FCommand/INclude will read in up to 1023 commands. You can nest INclude commands to get around the 1023 command limitation but BATUTIL is an interpreted language and such large projects should normally not be done using such a language. You can place multiple commands on a single FCommand line by separating them with one or more of the four characters [ ] { }. Chapter I:OVERVIEW Page 18 Documentation for BATUTIL, Version 4.0 Please look closely at the demonstration batch files for an introduction to how to use the file commands effectively. A typical batch file that only calls BATUTIL command including the RU command could have the form: @echo off batutil {INc %0 code} quitbat :code BATUTIL commands To make this work, you'd need a zero byte batch file called quitbat.bat in your path (you can make such a file at the DOS command line by typing in rem > quitbat.bat FEcho and FPretty are discussed in Section III.7 and FMenu in Section IV.2. BATUTIL stores the name of the last file you have asked to read commands, echo, pretty or menu from and will reuse it if you use the filename %0 in one of these commands. See the sample batch files. I.8 BATUTIL's line editor Four of BATUTIL's commands allow editing of line input: the EDenv and PAthedit commands which allow you to edit any environmental variable and your path, the USername command which prompts for a string to be matched and the $Q/$?/$N subcommands of BATUTIL's SEt which place information in the environment. When such input is asked for the following edit keys are active <Enter> accepts the current string and exits <Esc> restores the original value of the string; if that original value is empty, <Esc> blanks the line except, in that case, <Esc> with a blank line exits and returns an empty string <Left>, <Right> move the cursor by a character <^Left>, <^Right> move the cursor by a word <Home>, <End> to the beginning or end of the line <Ins> toggles insert mode which starts as overwrite mode; the cursor shape indicates what the current mode is <Del> and <Bks> do their usual single character functions <^X> or <^Y> blanks the entire line <^End> blanks to the end of the line <^Home> blanks from the start of the line ot the current Chapter I:OVERVIEW Page 19 Documentation for BATUTIL, Version 4.0 position. <^T> blanks from the cursor position through the next blank space In addition, WordStar commands are accepted for most of these functions, e.g. ^S is the same as <Left> and the two letter ^QS (or ^Q^S) is the same as <Home>. In situations where the quantity being edited has a prior value, that value is displayed when the line editor starts up and the cursor is at the end of line. Hitting an alphanumeric key (as opposed to a cursor key) as the first key will blank the original value which can be restored with <Esc>. The $N input must be an integer and only integer input is accepted. In each case, the input string has a maximum length which may be larger than the edit window on screen. If it is larger, the line editor with scroll horizontally if the cursor moves to the start or end of the edit window. The point is that the editor is quite intuitive and most users will have no trouble using it without explicit directions. I.9 BUSIC - a first look BATUTIL includes a full featured language which goes way beyond the DOS batch language. We dub it BUSIC for BatUtil's Standard Instructions and Commands. Despite the name it is closer to Pascal or C than BASIC. While it can be used at the command line, the use of {}'s gets tedious and we recommend limiting BUSIC to INclude sets of commands. Chapter VI is devoted to this language but we'll make a few general remarks here. There are 32 internal variables. Two are special - $r is like the RC environmental variable and $% tracks the last fileIO error when IOerrors are trapped. These two variables cannot be set with the set command but can be ECHOed with metastring translation or used in other places, e.g. inside a comparison after an IF, where they are read. You will most often use the internal variables $1,...,$0, ten in all. In addition while they are more awkward to use there are an additional 20 variables which are indicated by $ followed by one of the ASCII codes 130-149, that is $é, $â, ..., $ò. These can be set Chapter I:OVERVIEW Page 20 Documentation for BATUTIL, Version 4.0 with commands like SEt $1=.... The set is actually optional for these 30 variables, that is $1=$Q is the same as SEt $1=$Q and would place up an edit box whose value is stored in $1. The commands ++ $1 and -- $1 (where $1 is any of the 30 internal variables that you can set) will check to see if $1 is number (if it is not there will be an error exit!) and if so increase or decrease it by one. If the variable is empty, it is treated as if it were 0 for purposes of these commands. The keywords in the language cannot be abbreviated. We'll usually capitalize them for emphasis but they are not case sensitive. After THEN or ELSE in an IF clause, after FOR, after a CASE option, and after a WHILE or REPEAT, you need to place a legitimate BATUTIL command, for example IF $1>6 THEN ECho it is greater than 6 In all these cases you can replace the command by the single keyword begin and then place several commands each on a separate line (or separated by {}[]) with an END to indicate that you finished the set of commands started with a BEGIN. For example to count the files in a directory starting with b, echoing their names to the screen, you could use: $1=0 FOR $2 in (b*.*) DO BEGIN ++ $1 ECho $1:$2$_ END Our sample will indent commands between BEGIN/END pairs for readability but leading spaces are ignored by BUSIC. $R is a special metastring. It will read from a text file - see Section VI.5 for discussion of reading from file and writing to them. If the file you read from is "con", then special handling is done and you read from the screen. You can read from absolute screen positions or positions relative to the current one. Chapter I:OVERVIEW Page 21 Documentation for BATUTIL, Version 4.0 BATUTIL's TRace command is discussed in Section VI.12. There is a powerful but dangerous option that allows you to directly read and write from/to memory and or a processor IO port. Because we'd not want you to do this by accident, you must turn this mode on within EACH running of BATUTIL with a {HACKER +} command. We discuss this in Section VI.13. I.10 String manipulation, arithmetic and date arithmetic BATUTIL include special metastrings to handle string manipulation and arithmetic. $s (to be distinguished from $S=space) when translated manipulates a string. The syntax is $s(X,string,Y) where S is a single letter key and Y are parameters which are special to each value of X. For example $s(W,string,4) would become the fourth word in the string and $s(U,string) would make the string Uppercase. Section VI.2 describes this metastring in full details. $V (to be distinguished from $v=DOS version) does arithmetic. The syntax is to put an arithmetic string inside parenthesis following $V. For example $V(1+4) would translate to 5. Only integer arithmetic is done. Operations are summarized in Section VI.3. Multiple parentheses are handled and there is metastring translation inside the (..) so that you can use $1, etc and environmental variables. For example internally, BATUTIL translates ++$1 to SEt $1=$V($1+1) In Version 1.0 $E, $M, $D, $Y, $W referred to today in English, the month, day of month, year and weekday. That remains true IF these are not followed by a (. If they are BATUTIL will attempt to translate the argument into one of three formats 1. sees if it is number between 1 and 7305 and interprets it as a date between 1/1/80 and 12/31/99 2. sees if it has the format MM-DD-YY or MM/DD/YY and interprets it in that format as an American style date 3. looks for a filename with that name and interprets it as the date of that file. So, for example, if the file C:\dos\command.com has a date of Chapter I:OVERVIEW Page 22 Documentation for BATUTIL, Version 4.0 12/19/88, then all three of $E(12/19/88), $E(C:\dos\command.com) and $E(3276) would become December 19, 1988 after metastring translation. If the European date switch is turned on, then the date is interpreted as DD/MM/YY in place of MM/DD/YY. The use of number of days after 1/1/80 wouldn't be useful if you had to count the days yourself. So there is a metastring $J which counts that number of days. With no parameters, it is today and for example $J(12/19/88)=3276. Thus for example, you could do date arithmetic with batutil {EC the date 200 days from today is $E($V(200+$J))} I.11 Control Break handling BATUTIL looks especially for the user to press ^Break. If this is pressed during the running of BATUTIL, then the message ╒═══════════════════╕ │ Quit BATUTIL(Y/N)?│ ╘═══════════════════╛ pops up. If you answer yes, then BATUTIL pops up a message: ╒══════════════════════════╕ │ Halt Batch file too(Y/N)?│ ╘══════════════════════════╛ With either response to this question, BATUTIL is then halted. If you've also answered yes to the second question, then BATUTIL will turn DOS Break on and place a ^C buffer so the batch file should offer you the chance to terminate it. If you prefer running with Break off, you'll need to do that by hand if you use this emergency exit. This response is to ^Break only and NOT also to Ctrl-C. If you answer N to the initial "Quit BATUTIL" question, then BATUTIL will ask ╒════════════════════╕ │ Turn TRACE On(Y/N)?│ ╘════════════════════╛ Either way BATUTIL will continue but if you answer yes to the TRACE On question then BATUTIL's single step debug mode is turned on but not until the currently executing command is finished. If you quit BATUTIL with ^Break but elect not to halt the batch file, BATUTIL exits with the errorlevel set to 255. Chapter I:OVERVIEW Page 23 Documentation for BATUTIL, Version 4.0 For third party batch files, you may want to turn off ^Break to prevent the user from breaking at an inconvenient point. When BATUTIL loads, it checks to see if BU^=no is in the environment; if it is, then the ^-Break handler is not installed, so just include set BU^=no in the batch file to avoid this premature exit. Chapter I:OVERVIEW Page 24 Chapter II:SYSTEM INFORMATION II.1 Overview You can use BATUTIL to query the system to get information about the current date and time, the current drive, hardware information like the number of monitors or printer ports, and file information like whether a particular file exists on the DOS path. Related are a primitive MAKE command which examines two files and tells you which is older and a RUN command which will tell you the errorlevel that a subsidiary program returns. You can get the information stored in the special environment variable RC (and the internal variable $r) or in the errorlevel or both. For example, batutil [HO] returns the current hour in the errorlevel while batutil {HO} returns it in both RC and the errorlevel. Only the last {} command on the line has information returned in errorlevel. If any [] command is encountered then that is the last command that BATUTIL executes before exiting. Except for the internal FDir command, all commands discussed in this chapter are dual mode []/{} commands. If an intermediate result is stored in an environmental variable like RC, you can have it placed in the errorlevel with the ERrorlevel command as in batutil {HO}{EC The current hour is $x(rc)}[ER $x(rc)] The $x syntax is discussed in Section III.1. Many commands come in pairs like #Disk and @Disk starting with # or @. Typically, # refers to total and @ to free so that batutil [#D] places in the errorlevel the total space on the default drive and batutil [@D] the amount of free space. As in STACKEY, the left round parenthesis, (, is a synonym for @ and the right round parenthesis, ), for #. Thus the last command could also be batutil [(D] Commands have full names such as HOUR but any name can be abbreviated by using two or more letters as in HO or HOU. To emphasize this, we'll write the commands as HOur but that does not mean you have to type the command with that capitalization. BATUTIL's command interpreter is not case sensitive. When you want to squeeze a lot on the command line, you'll want to use the two letter abbreviation. Chapter II:SYSTEM INFORMATION Page 25 Documentation for BATUTIL, Version 4.0 You'll often want to use the SEt command and metastring expansion in connection with or instead of the commands of this chapter. The SEt command is described in Section V.3 and metastrings in Section III.1. As examples of what we mean, batutil {#Comm}{SEt comm=$x(rc)}{#Prn}{SEt prn=$x(rc)} would place the number of comm ports in the environment as comm=nn and then the number of printers as prn=nn but one wouldn't use batutil {HO}{SEt hour=$x(rc)} since there is a metastring for the current hour and one could just as well use batutil {SEt hour=$H} Moreover, the $M, $D, $Y, $W metastrings take an argument while the MO, DA, YE and WE commands do not. II.2 Time Commands: HOur, MInute, WEekday, DAte, MOnth, YEar You can return information on the time and date in the errorlevel as follows HOur the hour in military time from 0 to 23 MInute the number of minutes past the hour from 0 to 59 WEekday the day of the week from 0=Sunday to 6=Saturday DAte the day of the month from 1 to 31 MOnth the number of the month from 1 to 12 YEar the number of years since 1980 from 0 to 19 so in 1988 this would return 8. II.3 Operating System and Memory Information Commands: DOs, DRive, LIm, HImem, CArousel, DView, #Mem, @Mem, #Lim, @Lim, #Xtended, @Xtended, #Env, @Env, #Disk, @Disk Parameters: For #D and @D, no parameter picks default drive or you can give a drive letter. For DOs, nothing, "4", "N", "S", "F", "B", "L", or "W". You can return the following information about the operating environment: Chapter II:SYSTEM INFORMATION Page 26 Documentation for BATUTIL, Version 4.0 DOs returns the DOS Version times 10 rounded downwards so DOS 2.1 would return 21 and DOS 3.21 would return 32. "DOs 4" returns information about the program 4DOS from JP Software, an alternative to Command.com. If a swapping version of 4DOS is loaded anywhere in memory, then the value 1 is returned; otherwise the value 0 is returned. This requires 4DOS Version 2.1 or later. "DOs N" is like "DOs 4" except it tests for NDOS from Symantec's Norton division. "DOs S" tests whether DOS' share program is loaded. If it is the value returned is 1 and if it is not loaded, the value returned is 0. "DOs F" counts the number of DOS file handles in the system as set up in config.sys with additional handles set up with say QEMM's FILES program. This is the number in the system, rather than the number still available or the number in use. "DOs B" counts the number of DOS buffers in the same way. "DOs L" returns the number of possible logical drives the system can have as determined by the DOS Lastdrive parameter. "DOs W" returns information about whether BATUTIL is running in a DOS partition set up by Microsoft Windows and returns the following: 0 = Windows not running (or Windows 286 Versions prior to 3.0) 1 = Windows 3.x running in real or standard mode 2 = Windows 2.x /386 running 3 = Windows 3.x running in enhanced mode Since documented calls are used, this should work with Windows 3.1 when it is released. DRive returns the current drive with 0=A, 1=B, ...., 25=Z. This is the drive as DOS reports it so if SUBST is in effect, the subst letter will be used. LIm returns 0 if no EMS manager is installed and the Version times 10 rounded downwards so to check whether an EMS 4.0 driver is installed you'd use batutil [LI] Chapter II:SYSTEM INFORMATION Page 27 Documentation for BATUTIL, Version 4.0 if errorlevel 40 ..... HImem returns 0 if no XMS manager setting up the Microsoft Himem area is installed and a 1 if such a manager is installed. Examples of XMS managers are Himem, which comes with some Versions of Windows and DOS, 386Max and QEMM/386. CArousel returns 0 if SoftLogic's SOFTWARE CAROUSEL is not installed and otherwise returns the partition number from 1 to 12 (1 to 10 with Carousel Versions prior to 3.0). DView returns 0 if Quarterdeck's DESQVIEW is not installed and otherwise returns the partition number from 1 to 255. OView has been dropped in this version. You can also get information about memory and disk resources: #Mem returns the total conventional memory in units of 4K from 0 to 160 (160 means 640K); the amount is rounded down. If you have an appropriate program/hardware combination to have more than 640K of conventional memory (EEMRAM, 386 to the max or QEMM, for example), then the number returned may be more than 640K but it will never be more than 184. @Mem returns the free conventional memory in units of 4K. #Lim returns 0 if no EMS memory is present; otherwise, it returns the total EMS memory in units of 64K from 0 to 199. This is rounded down and with 12736K or more of EMS, 199 is returned. @Lim returns 0 if no EMS memory is present; otherwise, it returns the free EMS memory in units of 16K from 0 to 199. This is rounded down and with 3184K or more of free EMS, 199 is returned. #Xtended returns 0 if no extended memory is present; otherwise, it returns the total extended memory in units of 64K from 0 to 199. This is rounded down and with 12736K or more of extended memory, 199 is returned. @Xtended returns 0 if no extended memory is present; otherwise, it returns the "free" extended memory in units of 16K from 0 to 199. This is rounded down and with 3184K or more of Chapter II:SYSTEM INFORMATION Page 28 Documentation for BATUTIL, Version 4.0 extended memory, 199 is returned. Because there is no standard for extended memory usage, BATUTIL is not totally accurate in its count of free extended memory. It subtracts from the total available the amount used by VDISK and VDISK compatible programs. #Env returns the total amount of environment space in units of 16 bytes. See Section V.1 for a discussion of the DOS environment area. The answer can be from 0 to 199 with 199 corresponding to 3184 or more bytes. @Env returns the free environment space in units of 1 byte. The answer can be from 0 to 199 with the later indicated 199 or more. #Disk returns the total amount of disk space. An optional parameter is allowed of a letter. If no parameter is given, then the response is for the default drive. For drives A and B the errorlevel is space in units of 8K from 0 to 199 rounded down. If there is more than 1592K, a value of 199 is returned. For drives other than A, B the amount is in units of 256K from 0 to 199. For drives of 49.75 Meg or more (possible only under DOS Versions greater than 3.30 or with special software), 199 is returned. If an invalid drive letter is given, the errorlevel is set to 232. If there is a syntax error such as asking for {#D 7}, the errorlevel is set to 208. @Disk returns the amount of free space on a disk drive with the same parameters and errorlevels for errors as #D. For any drive, the amount free is reported in units of 8K from 0 to 199. With more than 1592K free, the value returned is 199. Please note that @D and #D use different units. II.4 Console Information Commands: #Terminal, @Terminal, #Vmode, #Whichmon, #Altmon, @Ansi, #Keyboard, #Rodent Parameters: For #T, nothing, R, C or S BATUTIL will give you information about the system monitors and keyboards as follows: #Terminal with no parameter returns the number of monitors you have, either 1 or 2. With the parameter R (or r or even Rows if you prefer), it returns the number of rows on the screen. IBM EGAs Chapter II:SYSTEM INFORMATION Page 29 Documentation for BATUTIL, Version 4.0 support 43 rows as well as 25 and VGAs support 50. Many superVGAs support 33, 36 or 60 rows. UltraVision also supports non-standard numbers of rows. Similar UltraVision and some SuperEGA or SuperVGAs support 120 or 132 columns and #T with the C parameter returns the number of columns. Some programs require 1 less than the number of rows so S, for Special as a parameter returns that. @Terminal returns the currently active monitor: 0 if mono and 1 if color (or CGA compatible B/W like the old style Compaq monitors). #Vmode returns the current video mode as reported by int 10H. #Whichmon returns the type of the current monitor according to the following table: 1 = monochrome (old style MDA) 2 = cga color 4 = ega color 5 = ega mono 6 = professional graphics controller 7 = vga mono 8 = vga color 11 = mcga mono 12 = mcga color 21 = hercules mono 22 = hercules monochrome plus (with RAM font) 23 = hercules Incolor If this ordering seems bizarre to you, it does to us also! The numbers below 20 are taken from the official "Display Combination Code" in the IBM PS/2 computer BIOS and who are we to argue with IBM? #Altmon returns information about the second monitor if you have one. Allowed values are 0 (which indicates no second monitor) and the numbers above. @Ansi returns 1 if an ANSI.SYS compatible console driver is installed and 0 otherwise. #Keyboard will return whether an "enhanced" keyboard is attached (the enhanced keyboard is the 101 key keyboard with the function keys across the top and the CapsLock where everyone knows the Ctrl key should be). A 0 response indicates a 84 key keyboard and a 1 the enhanced keyboard. Actually, BATUTIL is not testing Chapter II:SYSTEM INFORMATION Page 30 Documentation for BATUTIL, Version 4.0 the keyboard but rather the presence of BIOS support for the enhanced keyboard. #Rodent returns 1 if a Microsoft compatible mouse is found and 0 otherwise. II.5 Hardware Information Commands: #Intel, @Intel, #Prn, @Prn, #Comm, #Game, #Floppy, @Floppy Parameters: For @P, printer number from 1 to 3; no parameter picks LPT1. #Intel tests what CPU you have and reports as follows: 0 = 8086/8088 1 = 80186 2 = 80286 3 = 80386 4 = 80486 20 = NEC V20/V30 @Intel tests what kind of math coprocessor that you have and reports as follows: 0 = no math coprocessor 1 = 8087 2 = 80287 3 = 80387 4 = 80486 or 80486SX with 80487 installed #Prn reports the number of printers attached to your system (or more precisely the number that DOS thinks you have attached). @Prn returns error information for one of your printers. You can specify a printer number or, if none is given, LPT1 will be tested. The number returned means: 0 = printer status OK 1 = paper out error 2 = I/O error 3 = Timeout error 4 = invalid printer 5 = other printer error If you have a print spooler installed, you'll get a response of 0 even if the printer is offline or out of paper. Chapter II:SYSTEM INFORMATION Page 31 Documentation for BATUTIL, Version 4.0 #Comm returns the number of serial ports that you have; with more than 2 ports present, the method may not be reliable depending on how your non-DOS ports are added on. #Game returns the number of game ports that you have (or at least that BIOS thinks you have as stored in the equipment byte). Alas this number is often not accurate because not all game adapters are found by the BIOS. #Floppy returns the number of Diskette drives you have. @Floppy returns the following information 0 = you have none or more than 1 diskette drive 1 = you have a single diskette drive which is currently logical drive A 2 = you have a single diskette drive which is currently logical drive B II.6 File Information Commands: EXist, CHeck, NUmberfiles Parameters: for EXist - filename (no wildcards) for CHeck - pathname with or without trailing \ for NUmberfiles - filespec(s) with wildcards Internal Command: FDir BATUTIL has a number of commands that will return information about files on disk. Each of these commands must have a parameter describing the filespec of the file or path you want information about. They will only take a single parameter except for NUmberfiles. EXist is a more powerful version of DOS' "if exist" command. If a filename is given with no path or drive, the responses are 0 = the file exists in the default directory or the filename is the name of a device loaded in your config.sys (see below) 1 = the file does not exist in the current directory but it does exist somewhere on the PATH. The directory can be returned in an environmental variable; see the discussion of FDir below. 2 = the file does not exist in the path codes above 200 indicate DOS, syntax or environmental errors; see Chapter IX. If a path or drive is given as in "batutil {EX C:foobar.txt}" or "batutil {EX \bin\foobar.txt}", then the responses are Chapter II:SYSTEM INFORMATION Page 32 Documentation for BATUTIL, Version 4.0 0 = the file exists in the specified drive and/or directory 2 = the file does not exist in the specified drive and/or directory 9 = the path given is not a valid path codes above 200 indicate DOS, syntax or environmental errors; see Chapter IX. EX does not interpret wildcards, that is if you look for a file named foo*.* as in "batutil {ex foo*.*}", then BATUTIL will look precisely for a file with that exact name and not find it. If a filename with no explicit path is entered as the parameter for EX and the file is not found in the current directory, then the DOS path is searched for it and optionally, the directory where it is found is placed in the environment. By default, the name FDIR is used so that if foobar.txt existed in directory C:\bin which was in your path, then after running batutil {EX foobar.txt} RC would have the value 1 and FDIR the value C:\bin, that is a DOS SET (or batutil {ENvrep}) will include FDIR=C:\BIN RC=1 The FDir command allows you to change where this directory name is stored. If no new name is given then the directory name is not stored so batutil {FD}{EX foobar.txt} would not store the name C:\BIN anywhere while batutil {FD foo}{EX foobar.txt} would store the string FOO=C:\BIN You might want to use this directory name in a way that requires a backslash; for example you might want to copy the file. Just adding the backslash by hand won't work if the directory is the root (which already ends in a backslash). If you use FDIR to define a variable which begins with a \, then a trailing backslash is added. Thus batutil {FD \foo}{EX foobar.txt} would store the string \FOO=C:\BIN\ and you could then use the command copy %\foo%foobar.txt A: FDIR is also used by the $f file picklist discussed in Section V.5. Chapter II:SYSTEM INFORMATION Page 33 Documentation for BATUTIL, Version 4.0 If your machine has a config.sys file, it likely loads various device drivers with the "device=" command. In addition, DOS sets up various devices like NUL, CON, PRN and LPT2. Some of the devices have explicit names. For example, any EMS driver will call its device EMMXXXX0, the memory manager 386 to the Max calls its device 386MAX$$ and the Microsoft Himem program loads a device called XMSXXXX0. If you use DOS' "if exist" it will recognize a device in any directory, so, for example if exist \somepath\nul echo hi will echo if and only if the directory \somepath\ exists. In the same way, batutil {EX ...} will return a code of 0 if ... is a device. But to distinguish devices from files, it does an extra check to see if the specified file is a device. If it is, it sets FDIR (or whatever you've replaced fdir by with the FDIR command) to the value IS_A_DEVICE. CHeck will check whether a path exists and reply 0 if it does and 9 if it does not. You can include a tailing backslash or not as you wish. If you want a batch file to act differently depending on whether A: has a diskette in it or not, use batutil Q {CH A:\} which will return errorlevel 0 if there is a diskette and errorlevel 230 (drive not ready) if not. If you used if exist A:\nul instead and no diskette were there, the batch file would halt with an Abort, Retry, Fail message. NUmberfiles takes a filespec with wildcards and tells you how many files match in the default directory match that filespec, for example batutil {NU C:\bin\*.*} would tell you the total number of files in that directory. The answer will be between 0 and 199; the answer 199 indicates that there are 199 or more matching files. NU will take more than one file spec so that batutil {NU C:\bin\*.com C:\bin\*.exe} would tell you the total number of executables in C:\bin. II.7 The RUn Command Command: RUn, SKey Parameter: program name for RUn, Stackey strings for SKey Chapter II:SYSTEM INFORMATION Page 34 Documentation for BATUTIL, Version 4.0 BATUTIL has a command that will let you run another program and get the errorlevel that program exits with recorded in the environment as the value of RC. The syntax is batutil {RU programname} programname can include a path if you wish. Like DOS, BATUTIL will ignore any extension that you give and first try a COM file and then an EXE file. Afterward the program has run, RC will be set to the errorlevel of programname. A typical application of this would be to get the errorlevel reported on screen by batutil {RU programname}{EC $x(RC)} For this purpose, a stand alone program called WHATEL is provided. Just type in WHATEL programname and the program will report the errorlevel and the time it took programname to run. This time is rounded up in units of 55 milliseconds (the smallest unit of time one can measure without reprogammming the PC's internal clock) so that time differences of .06 seconds are insignificant. batutil {RU ...} will always swap to disk or EMS (see below) and leaves about 11K of memory for the stub or BATUTIL to reload after the RU command is done. The disk space or EMS taken is about 300K; WHATEL does not swap and takes less than 17K. There is a slight difference between how batutil {RU ...} and WHATEL work. The former searches for a COM or EXE executable binary file in the current directory or on the path. It will yield an error message if you use a batch file name, DOS internal command or bad command name. You can always proceed the batch file name or internal command by command /c and the RUn command will run properly if command.com is on your path. Since WHATEL is also a timing utility, it might be used for batch files, internal commands or even to time a bad command. So, if WHATEL cannot locate a suitable COM or EXE file, it passes your command to DOS to see if DOS can make sense if it. In that case instead of reporting: "Errorlevel returned by ... was ..." WHATEL reports "...run from a shell of DOS". The RUn command will swap BATUTIL to EMS by default. Otherwise it will swap to the current directory. The filename that it uses $$$$$$BU.SWP. Any filename of this name will be replaced without Chapter II:SYSTEM INFORMATION Page 35 Documentation for BATUTIL, Version 4.0 warning when the swap takes place and erased after the swap. The swapfile is given the attributes Hidden and System. If the swap directory is a floppy disk or insufficient space is available on the swap drive and insufficient space is available in EMS, then BATUTIL will exit with errorlevel set to 238 and if verbose mode is on you'll get an error message 'RUN error: Swap file open error or bad path'. You can control where BATUTIL swaps to and if EMS is used with the environmental variable BUSWAP. If BUSWAP=path then that path is used for the swap file. For example if F: is a large ram disk, you might use BUSWAP=F:\ If BUSWAP=-path with a minus sign in front of the path, then BATUTIL will force a disk swap and not use EMS. If you do not want BATUTIL to be swapped out at all (in which case BATUTIL continues to take about 300K of memory) just set BUSWAP to the value !, that is use set BUSWAP=! Three other errors that can occur when you try a RUn command are 235: Program not found 236: Insufficient memory to run program 237: Misc. DOS error As with other cases where you shell from a program, you should be careful not to load any resident programs (TSRs) from a batch file executed with the RUn command. If you do, you will likely crash when you attempt to return to BATUTIL. If STACKEY is loaded before BATUTIL, you can use the RUn command to first load keystrokes for a program you RUn from BATUTIL. But to avoid having to swap out BATUTIL twice, you can use BATUTIL to directly talk to STACKEY. You use the SKey command followed by an appropriate STACKEY string. Not all STACKEY commands are support but the following are - with STACKEY syntax: all ^ control combinations all 40 (shifted) function keys Chapter II:SYSTEM INFORMATION Page 36 Documentation for BATUTIL, Version 4.0 the alt-key combos that start with @ the cursor pad combos like UA ES, BS, TA, TB, ST, BT, CR, LF, FF, SP, SQ, DQ Xnnnn and #nnn single key input Wnnn waits ! buffer flush (only as a single command) strings in ".." or '..' $ metastrings as translated by BATUTIL except for $X, $x, $L, $A, $a, $B, $C, $s, $V ,$Q, $?, $N, $F, $f, $R, $Z, $z $E, $J, $M, $D, $J are supported for today but not with (..) arguments II.8 TOdayfile and MAkefile Commands: TOdayfile, MAkefile Parameters: For TOdayfile: either a filename or an hour and a filename; for MAkefile: two filenames The TOdayfile command is intended to tell you whether a given file has today's date. As we'll explain in Chapter VII, it is intended for use in a batch file, usually an autoexec.bat file, to make sure that some operation is only done once a day. In the simplest form, the syntax is batutil {TO filename} and the responses are 0 = the file has today's date 1 = the file exists and doesn't have today's date 2 = file not found 9 = invalid path above 200; DOS and syntax errors as in Chapter IX; allowed values are 230, 231 (for DOS error) or 204 - 207 (for syntax errors). If you wish, TO will take an optional numeric parameter as its first parameter, i.e. with syntax batutil {TO hour filename} where hour is between 0 and 23. This parameter is used if you'd like the day to begin at a time other than midnight (0 is therefore a redundant choice put in only for completeness). For example if you type in batutil {TO 5 test.dat} then BATUTIL will look at days beginning at 5 in the morning and see whether test.dat and the current date/time are on the same Chapter II:SYSTEM INFORMATION Page 37 Documentation for BATUTIL, Version 4.0 "day". Thus if test.dat was made yesterday at 8:15 AM the above command would return an errorlevel of 0 if the current time is before 5 AM and an errorlevel of 1 if after 5 AM. This will prevent an action from happening if you stay up late at night and don't want to think of that as a new day. MAkefile requires two file names which we'll call file1 and file2. The errorlevel returned is as follows: 0 = file2 not found 1 = file2 is strictly older 2 = file1 not found 3 = file1 older or the same age as file2 9 = path not found above 200; DOS and syntax errors as in Chapter IX; allowed values are 230, 231 (for DOS disk errors) and 204,205 (for syntax error) This choice is made because if file2 doesn't exist or is older, one will want to take an action like compile something or backup something else. II.9 The ERrorlevel Command Command: ERrorlevel Parameter: integer from 0 to 255 You can set the errorlevel to a prescribed number between 0 and 199 with the ERrorlevel command. ER must be followed by a number or by a metastring beginning with $ that translate into a number or by $$ followed by a hex number. If, after metastring translation, the parameter is not a number, BATUTIL exits with the errorlevel set to 206 (and an error message if Verbose mode is on). If the number is less than 0, 0 is returned and if greater than 199, then 199 is returned. For example batutil [ER $H] is the same as batutil [HO] and batutil ....[ER $r] would set the exit errorlevel to the value of RC set by an earlier command. Chapter II:SYSTEM INFORMATION Page 38 Chapter III: DISPLAY TOOLS III.1 Overview One of the most important aspects of a batch files on which DOS is woefully inadequate is communicating with the batch file user. In this chapter, we'll discuss enhancements to better display messages giving you control on colors, on where the messages are displayed and allowing you easily place system information like the current drive in your messages. BATUTIL also provides 10 sounds and 10 tunes with you can use to communicate with the batch file user. In the next chapter we'll discuss the tools that BATUTIL gives you to get input from the user. One of those methods pops up a menu and another pops up a file list and so they also involve display. In Section III.2, we'll discuss some automatic translation that gets done when you ask BATUTIL to display a string. This translation mechanism is also relevant to the SEt command discussed in Section V.3, when you write to a file (see Section VI.5) and, if you wish when you read from a file (also in Section VI.5). By default, BATUTIL displays by writing directly to the screen but as we'll discuss in Section III.9, you can instruct BATUTIL to use standard output if you wish to redirect the ECho command to a file or printer. III.2 Metastring Translation Commands: $Translate, ^Translate Parameters: - to turn off Metastrings: $$, $t, $d, $p, $v, $n, $g,$l, $b, $q, $h, $e, $_, $P, $T, $M, $D, $Y, $W, $E, $H, $m, $S, $^, $(, $), $`, $', $a, $A, $B, $C, $X, $x The DOS PROMPT command supports a set of what the DOS manual calls metastrings; something like $p is translated into the current path name. STACKEY extended this set of metastrings. BATUTIL uses all the STACKEY metastrings and adds a few extra ones to accommodate its special structure. This metastring translation takes place for the ECho and PRetty commands discussed in this chapter, the MEnu command of the next chapter, the SEt command of Chapter V, and the commands for reading and writing files. As we'll explain, you can tell BATUTIL not to make the translation if you wish. Here are the PROMPT metastrings, all of which are used by BATUTIL: Chapter III: DISPLAY TOOLS Page 39 Documentation for BATUTIL, Version 4.0 $$ The character "$" $t The time in HH:MM:SS.hh format $d The date in DAY MM-DD-YYYY format e.g. Tue 9-30-1986 If European dates are set then the format is DAY DD/MM/YYYY $p The current path in full, e.g. C:\BIN\FOO $v The current DOS version $n The current default drive $g The character ">" $l The character "<" $b The character "|" $q The character "=" $h The backspace $e The ESCape $_ CR/LF (i.e. <Enter> followed by Ctrl-<Enter> and the special STACKEY metastrings which are used by BATUTIL: $P same as $p in the root dir and as $p\ elsewhere $T time in HHMM format $M month in MM format, e.g. 09 $D day in DD format, e.g. 03 $Y year in YY format, e.g. 86 in 1986 and 99 in 1999 $W day of the week in English, e.g. Sunday $E the date in English, e.g. February 18, 1988 or if European dates are set 18 February 1988 $H hour from 00 to 23 $m minute from 0 to 59 and BATUTIL will make the translation of ^ to indicate a control character, e.g. ^A and ^B will display happy faces. $M, $D, $Y, $W and $E have BATUTIL extensions if immediately followed with no spaces by an argument in (..), for example $E(12/31/89). If the argument is an integer between 1 and 7305, the argument is interpreted as the number of days after 12/31/79 (7305 is special because $E(7305) = December 31, 1999). Otherwise, BATUTIL looks for a date in the format MM/DD/YY or MM-DD-YY with YY in the interval 80-99 or 1980- 1999, MM in the interval 1-12 and DD in the interval 1-31 (if European dates are set, then DD/MM/YY is used rather than MM/DD/YY). So, for example, $W(11/23/89) = Thursday. If the argument is neither an integer or a valid date, BATUTIL will try to interpret it as filename and if the file exists use its date as the basis for the translation. The number of days since 12/31/79 is important for date arithmetic so Chapter III: DISPLAY TOOLS Page 40 Documentation for BATUTIL, Version 4.0 $J Julian calendar days from 12/31/79 With no argument, $J is for today - otherwise it uses the same rules as #E, etc. For example (with $V the eValuate metastring) $V($J(4/16/87)-$J(1/24/84)) would be translated by BATUTIL to 1178, the number of days between April 16, 1987 and January 24, 1984. In addition, there are several metastrings special to BATUTIL starting with some simple translations: $S a space $^ The character ^ $( The character { $) The character } $` The character [ $' The character ] The $S is necessary in situations where BATUTIL uses spaces to separate parameters and you want a space in a string. For example batutil {ME a b c} would pop up a menu of the form ╒═══╕ │ a │ │ b │ │ c │ ╘═══╛ while batutil {ME a$Sb c} would pop up a menu of the form ╒═════╕ │ a b │ │ c │ ╘═════╛ $(, $), $` and $' are needed because {,},[,] are command separators for BATUTIL and their use in the middle of a display string would likely produce something other than what you want. BATUTIL will do filename parsing; if ... is a filename, then $a(...) = path of ... without trailing backslash $A(...) = path of ... with trailing backslash added $B(...) = name of ... $C(...) = extension of .... Note that these commands are case sensitive. For example Chapter III: DISPLAY TOOLS Page 41 Documentation for BATUTIL, Version 4.0 $A(C:\bin\batfiles\foobar.bat) = C:\bin\batfiles\ $a(C:\bin\batfiles\foobar.bat) = C:\bin\batfiles $B(C:\bin\batfiles\foobar.bat) = foobar $C(C:\bin\batfiles\foobar.bat) = bat Metastring translation is not done on the string in ... with one crucial exception. The $x/$X environmental substitution is made. The most common use of these filename parsers would be to use the $f command to have the user choose a file from a popup list which you could then parse, e.g. batutil {EC Pick file}{SEt foo=$f fooext=$C($x(foo))} You can access environmental variables with either $x(var) or $X(var) where "var" is the name of an environment variable. $X will first translate the string using metastring translation while $x will not. Thus if your environment includes FOO=$p the DOS level command batutil {EC $x(foo)} would display the string $p on the screen while batutil {EC $X(foo)} would display the current directory. You can have a $x or $X as part of the variable being translated by $X in which case there is recursion. To avoid a crash if an infinite loop results as it would if foo1=$X(foo2) and foo2=$X(foo1), $X's are only translated 60 times at which point no further translation is done. When preparing batch files for third parties, use caution with $X. If there is a metastring syntax error (like using $j, an improper metastring) in foo, then use of $X(foo) will cause BATUTIL to exit with error 209. There are two subtle differences between the $x command and using DOS' %...% command. There is no effective difference between batutil {EC $x(foo)} and batutil {EC %foo%} but if your environment starts out with FOO=initial then batutil {SEt foo=final}{EC $x(foo)} would display "final" on the screen while batutil {SEt foo=final}{EC %foo%} would display "initial" on the screen. In addition, DOS does the translation of %foo% before passing the command onto BATUTIL which could bring the command line above the maximum 127 characters Chapter III: DISPLAY TOOLS Page 42 Documentation for BATUTIL, Version 4.0 supported by DOS while BATUTIL only expands $x(foo) after getting the command line and there is not the same limitation. In the SEt command, $Q, $?, $¿, $N and $f have special meaning; see the discussion Sections V.4 and V.5. In connection with the {GEtkey WAit} command, $L sets the location of a time countdown if used in an ECho or PRetty command. See the discussion in Section IV.5 BATUTIL's 32 internal variables are indicated with $- metastrings and are discussed in Section VI.1. $R is used for reading from a file and is discussed in Section VI.5. $s is for string manipulation and $V for arithmetic - they are discussed in Sections VI.2 and VI.3. $Z and $z are part of hacker mode discussed in Section VI.13. The supermetastring $!(...) is discussed in Section I.5. If you wish to turn off metastring translation, you can with the commands $T - to turn off $ translation $T to turn $ translation back on ^T - to turn off ^ translation ^T to turn ^ translation back on It is important to bear in mind that BATUTIL has no memory from one running to the next so that batutil {$T -}{EC $p}{$T}{EC $q$p} would display $p=C:\BIN if BIN were your current directory but batutil {$T -} batutil {EC $p}{$T}{EC $q$p} would display C:\BIN=C:\BIN III.3 BATUTIL's ECho Command Commands: ECho, ATtribute, MNattribute, CLs, EOline, ECHOLN Parameters: EC takes the string to echo AT, MN take a hex byte. AT T is also legal; see Section IV.5 EOline takes an optional parameter of + Chapter III: DISPLAY TOOLS Page 43 Documentation for BATUTIL, Version 4.0 You can echo a string to the screen with the FEcho command discussed in Section III.5 below or with batutil {EC string} The reasons to use BATUTIL's echo rather than DOS' echo are the following - metastring translation takes place with BATUTIL - there is not an automatic CR (which means you'll need to remember to add $_) but you can place several lines of text on one echo line (subject to DOS' 127 character limitation) by using $_. Use ECHOLN to add an automatic CR. - if you use BATUTIL's ECho command between two cursor location commands, BATUTIL will only be loaded once while if you use DOS' echo it will not - as we'll explain, BATUTIL gives you color control BATUTIL stores away two color combinations that it uses: one for color screens which defaults to yellow on blue and one for monochrome screens which defaults to dull foreground (attribute 07 hex). This attribute is used in several places: it is used by the ECho command it is used to set the colors by the CLs command it is used for shadows in the MEnu command (Section IV.2) it is used to determine the attributes in the input box for the $? query command (Section V.4) You can change the attributes used with the ATtribute and MNattribute commands. Each takes a hex byte either in the form 1A or $1A. The color values are those which are popped up in CTRLALT PLUS' ^@R or CTRLALT's ^@T table. The first digit is the background and the second foreground with the following rules Background Foreground 0 Black Black 1 Blue Blue 2 Green Green 3 Cyan Cyan 4 Red Red 5 Magenta Magenta 6 Brown Brown 7 Grey Grey 8 Black+Blinking Dark Grey 9 Blue+Blinking Light Blue A Green+Blinking Light Green B Cyan+Blinking Light Cyan C Red+Blinking Light Red D Magenta+Blinking Light Magenta Chapter III: DISPLAY TOOLS Page 44 Documentation for BATUTIL, Version 4.0 E Brown+Blinking Yellow F Grey+Blinking White where "blinking" refers to the foreground and should be used sparingly. For example, AT=$AF would set the attribute to blinking white on green (ugh!). For the hex digits a-f, you may use upper or lower case. Two attributes are special: $55 and $66. $55 tells BATUTIL to use the attributes at the cursor position at the time the string writing begins as the attributes for the entire string. $66 tells BATUTIL to write without changing any attributes. These two are the same if the block to be written to has uniform attributes but different if they the attributes change as the block is traversed. CLs clears the screen in the current ATtribute or MNattribute and sets the cursor to the upper left. Here is an example using the ROw and COlumn commands discussed below: batutil {CL}{AT=4F}{RO=15}{CO=5}{EC Hi! there} which would clear the screen in the default attributes of yellow on blue and then display "Hi! there" in white on red starting at row 15, column 5. EOline, short for "End of Line" will erase the current line from the cursor position until the end of the line in the current attributes. If you use a parameter of + as in batutil {EO +} then the entire line is erased. BATUTIL strips leading and tailing blanks from the string following EC so that {EC hi } is the same as {EC hi}. If you actually want the leading or tailing blanks, you'll need to use $S as in {EC $S hi $S}. Note that the blanks between the first/final $S and "hi" are not stripped. III.4 The BOx Command Command: BOx Parameters: top bottom left right [frame movecur] You can display a box with or without frame with a single BATUTIL command. The BOx command has four required parameters and two optional ones. The four required parameters specify the top and bottom row and the left and right columns. That is the upper left corner is at coordinates x=left, y=top and the lower right at Chapter III: DISPLAY TOOLS Page 45 Documentation for BATUTIL, Version 4.0 x=right, y=bottom. Normally, bottom must be at least two more than top and right at least two more than left of BATUTIL will exit with an error but if top=bottom (resp. left=right), then the box is centered vertically (resp. horizontally) and the height (resp. width) is the common value. Metastring translation is done on these four parameters. The color attribute used for the box including frame is the one set by the ATtribute command of MNattribute commands. By default, the frame is a single line but you can use an optional fifth parameter which is a number from 0 to 5. The value 0 means no frame and 1-5 mean (with 1 the default) ┌──┐ ╔══╗ ╒══╕ ╓──╖ +--+ 1: │ │ 2: ║ ║ 3: │ │ 4: ║ ║ 5: | | └──┘ ╚══╝ ╘══╛ ╙──╜ +--+ Notice that 1 and 2 have one and two lines all around, 3 more lines horizontal than vertical just like the numeral and similarly for 4. By default, after the box is drawn, the cursor moves to the position on the inside upper left ready for writing text. If you don't want the cursor to move use the parameter N in the fifth or sixth place. If you use the {SH +} command, then the box will display a shadow one character wide. The attribute used is black by default but the attribute used is the value of the internal variable $8 (be sure to set it to 0 or the empty string if you've used it earlier!) which we discuss the setting of in Section VI.1. If the attribute is XY, then attribute Y is used for the right and top half of the bottom shadow and X is used for the lower half of the bottom shadow. III.5 The PRetty Command Command: PRetty Parameters: string to display with @<Hex> for attribute change With the ECho command, you can display strings in multiple colors but it is rather tedious to have to write: batutil {AT 4F}{EC H}{AT 4E}{EC ello} to display Hello with the H in white on read and the rest in yellow on red. The PRetty Chapter III: DISPLAY TOOLS Page 46 Documentation for BATUTIL, Version 4.0 command lets you use the @ sign to signal a color change. If the @ sign is followed by two hex digits (or a $ and two hex digits), then the string following it will be displayed in that color until the next @ sign. So the above command line could be replace by batutil {PR @4FH@4Eello} Until you specify a new attribute with an @ command, PR will use the attributes set with the AT and MN commands (or their defaults 1E and 07). Irrespective of what you do with @ commands, when you complete a PR command (i.e. the closing } occurs), the value of AT and MN that were in place before will be in effect, for example batutil {AT 4E}{PR @20 hi$S}{EC there} will display "hi " in black on green (attribute 20) but then "there" in yellow on red (attribute 4E). As for the AT and MN commands, the HEX digits following @ can have a-f upper or lower case and an optional $ after the @ is allowed. III.6 Bigecho Commands: BEcho, BPretty, BIgchar Parameters: for BEcho: string to echo with special meanings for leading or trailing ~ or a trailing ^ for BPretty: string with PRetty @ commands; special meaning to trailing ^ for BIgchar: a foreground character and optional second background character. Each can be a character or a number from 1 to 255 (255 has special meaning). BIGECHO is a free program from Ctrlalt Associates available on many bulletin boards. As its name implies, it echoes large characters to the screen. One font is 8 characters high and 8 wide and uses the built in CGA character set found in ROM. There are additional smaller sets based on publicly available EGA fonts. BATUTIL includes a BIgecho command which uses the builtin 8x8 font. That is, messages displayed with it are eight lines (except for letters like j and g, the eighth line is blank) and are eight characters wide which means that up to 10 characters can be displayed on a line. The simplest command is BEcho which followed by a string displays that string in the large characters. The current Chapter III: DISPLAY TOOLS Page 47 Documentation for BATUTIL, Version 4.0 attribute set with AT (or MN) is used. Any characters that don't fit on the line will be truncated (this may be fewer than 10 characters if you don't start with the cursor in column 1). At the end of the line a "big carriage return" is issued, i.e. the cursor is moved to the first column of the row below the big characters. As we'll explain below, a leading ~ or trailing ^ or ~ will be suppressed and special actions will take place. Each character is stored as a set of dot patterns with the on dots normally displayed as the "foreground" color and the off dots as the "background color". Thus the letter R is stored as the dot pattern (1 = on, 0 = off) 11111100 $$$$$$ 01100110 $$ $$ 01100110 $$ $$ 01111100 corresponding to $$$$$ 01101100 $$ $$ 01100110 $$ $$ 11100110 $$$ $$ By default, BATUTIL, when BEchoing will replace each off dot by a space (character 32 in the ASCII scheme) and each on dot by the solid block (ASCII 219) so that R becomes ██████ ██ ██ ██ ██ █████ ██ ██ ██ ██ ███ ██ However, you can replace these two characters by any pair of characters using the BIgchar command. This command takes one or two parameters. The first parameter specifies the character used for "on" dots while the second, which is optional, the character for off dots. If the second parameter is absent, the off character is left unchanged from what it was (or from the default space if you haven't changed it). The parameters can be either a single ASCII character or a number from 01 to 255. To distinguish a number less than 10 from the corresponding ASCII character, place a 0 in front of the number. Thus {BI 1} will use "1" for the on character while {BI 01} will use a happy face (ASCII 1). Hex digits if proceeded with a $ are also allowed (e.g. $20 in place of 32). For example, to show the pattern ╬╬ ╬ ╬╬ ╬ Chapter III: DISPLAY TOOLS Page 48 Documentation for BATUTIL, Version 4.0 ╬ ╬╬ ╬ ╬ ╬╬ ╬ ╬ ╬╬ ╬ ╬╬ ╬ ╬╬ ╬ ╬╬╬╬╬╬╬╬ you'd want to use {BI 32 ╬} or {BI 32 206} or {BI $20 $CE}. Use of the on character 255 is special. It is interpreted to use the character itself for the on character (and space for the off character) so batutil {BI 255}{BE Hi there} would yield HH HH ii t hhh HH HH tt hh HH HH iii ttttt hh hh eeee rr rrr eeee HHHHHH ii tt hhh hh ee ee rrr rr ee ee HH HH ii tt hh hh eeeeee rr rr eeeeee HH HH ii tt t hh hh ee rr ee HH HH iiii tt hhh hh eeee rrrr eeee Metastring translation takes place for the BEchoed string. You'll use this mainly for $S spaces at the start (although it may be more useful to use the CO command to adjust the column of the cursor). If you do not want the big CR which is issued by default, end the string with a ^. The cursor is then left on the initial row in the column where the next large character would have appeared. Thus batutil {BI 255}{BE B^}{BI 219}{BE at} would yield BBBBBB █ BB BB ██ BB BB ████ █████ BBBBB ██ ██ BB BB █████ ██ BB BB ██ ██ ██ █ BBBBBB ███ ██ ██ If you have an off character other than the default space, BATUTIL assumes that you want the entire line to covered with that character except where the foreground appears (try batutil {BI 32 206}{CO 9}{BE Hi there} to see what we mean). If you don't want this effect, add ~ both before and after the string as in {BE ~Hi there~}. A ~ at the Chapter III: DISPLAY TOOLS Page 49 Documentation for BATUTIL, Version 4.0 start of the only will not fill in the space before the string. When a non-space off character is used, a ^ at the end and a ~ at the beginning also suppresses filling in spaces after the string. BPretty is like BEcho with the following changes: - as with Pretty, you can use @ followed by a hex attribute to change colors - off character fillin as described above for BEcho does not take place so leading and trailing ~ characters have no effect (but are stripped off). You cannot redirect BEcho or BPretty to STDOUT (i.e. {ST +} will be ignored by these commands). III.7 Getting Echo/Pretty Input from a File Commands: FEcho, FPretty Parameters: filename, optional label as second parameter If you have several lines to display, using the ECho or PRetty commands can be a nuisance. You'll have to prepare several BATUTIL lines in your batch file. For convenience, there are the FEcho and FPretty commands which take input for ECho and PRetty from a file. Rules for finding the filename (your path is searched) and the use of labels are discussed in Section I.5. Lines are read in from the file and processed as they would be by the ECho or PRetty command with two exceptions: - leading and trailing blanks are not striped off - that is lines will display as they appear. - each new line in the file causes a new line on the display except that there is not a new line command issued for the last line displayed (unless it ends in a $_). In particular, blank lines in the file display as blank lines on the screen. Unless turned off with the $T - command, full metastring translation takes place and @ color changes are done by FPretty. III.8 Cursor Position and Hiding the Cursor Commands: ROw, COl, CUrsor Parameter: RO takes a number from 1 to 25; may begin with + or -. A T is also legal; see Section IV.5 CO takes a number from 1 to 80; may begin with + Chapter III: DISPLAY TOOLS Page 50 Documentation for BATUTIL, Version 4.0 or -. A T is also legal; see Section IV.5 CU takes + or - If you want a screen in a batch file to begin with 10 blank lines under DOS, you've got to have 10 lines with echo <char 255> (where <char 255> is the ASCII 255 character) or something similar. BATUTIL allows you to control cursor position. {ROw n} where n runs from 1 to 25 sends the cursor to row n and similar {COl n} to column n. If just a number is listed after RO or CO, then the coordinates are absolute but if you precede then with a + or -, then the coordinates are relative. For example batutil {RO 5}{CO 5}{EC hi}{RO -3}{CO +3}{EC there} would print "hi" on row 5, col 5 and then "there" on row 2, column 10 (since writing "hi" move the cursor to column 7). BATUTIL will not wrap to the next line with relative coordinates and it will stop at the right or left edge if a relative coordinate shift would take it off the screen. The same is true of the top. However, if a relative row shift would take it below the bottom edge, it will scroll the screen. It is often more elegant if the cursor is hidden when you are displaying a message on the screen. {CUrsor -} will hide the cursor while {CUrsor +} will restore it to normal shape. When BATUTIL finishes running, the cursor is automatically restored so you'll only need {CU +} if you want the cursor to reappear in the middle of a sequence of commands. Places where you'd normally want BATUTIL to show a cursor like $Q in a set command, BATUTIL will show a cursor even if {CU -} is in effect so you'll only use {CU +} rarely. III.9 The STdout Command Command: STdout Parameter: + or - DOS' echo command is sent to standard output while, by default, BATUTIL will write directly to the screen. If you want EC to go to standard output, use {STdout +}. To turn off this use {STdout -}. Chapter III: DISPLAY TOOLS Page 51 Documentation for BATUTIL, Version 4.0 You would use {ST +} (the + is not necessary) if you wanted to redirect the output of the EC command (or of the messages from the SA, LO or KI commands) to a file or to NUL. To make a beep in the middle of a BATUTIL sequence, redirect output to STDOUT and echo a ^G as in batutil {ST}{EC ^G}{ST -}{EC You dummy!!!} If you echo to the screen with ST in effect, color commands have no effect. III.10 Sounds Command: SOund, NSound Parameter: SOund takes a single required number from 1 to 20 and an optional second number NSound takes a - or an optional + BATUTIL comes with ten brief sounds and ten tunes - the ten tunes were made with PIANOMAN. Each has a number; the ten sounds: 1:ping 2:wolf whistle 3:random electronic sound (needs a repeat to sound much) 4:short buzz 5:tweet 6:alarm clock ring 7:buzzer 8:electronic sound 1 9:electronic sound 2 10:train with Doppler effect while the tunes are fragments from: 11:Dance of the Clowns 12:Habana from Carmen 13:Sailor's Hornpipe 14:Mapleleaf Rag 15:Land of Hope and Glory (Pomp and Circumstance) 16:Porky Pig Theme ("That's All Folks") 17:Pop Goes the Weasel 18:William Tell Overture (Lone Ranger's Theme), part I 19:William Tell Overture (Lone Ranger's Theme), part II 20:Yellow Rose of Texas Chapter III: DISPLAY TOOLS Page 52 Documentation for BATUTIL, Version 4.0 You invoke a sound with BATUTIL by using the sound command which takes one or two parameters. The first parameter must be an integer from 1 to 20 and indicates the sound from the above list. The second parameter indicates the number of times to repeat the sound; if the second parameter is absent the sound is issued once. For most sounds you won't want any repeats but for sound 3, you'll want a repeat count of 15 or more and sound 4 will do with a few repeats. The repeat count must lie between 1 and 60. Thus batutil {SO 3 30} will repeat sound 3 thirty times. The William Tell Overture is broken into two parts, to allow you to take an action in the middle as in batutil {EC CTRLALT Associates}{SO 18}{EC $Spresents}{SO 19} If you don't want the SOund command issued, you can use the NSound command. This is intended primarily for use in the options set in the environment as in set @BU={NS} which would be useful if you normally had sounds in your batch files but were working late at night and didn't want to disturb others. The {NS -} command would turn sound back on even if there is a previous {NS}. Chapter III: DISPLAY TOOLS Page 53 Chapter IV:USER INPUT IV.1 Menu Basics Command: MEnu, NMouse Parameter: for MEnu, list of choices DOS provides very little in the way of user input to batch files - essentially the only way to modify the way a batch file runs from one time to the next is to change the parameters on the command line. BATUTIL provides a number of alternates which we'll discuss in this chapter: you can pop up a menu from which the user chooses and have the choice returned in the errorlevel, you can have the user hit one of a specified number of keys, you can react to a specified state of the Capslock or Numlock or use a number of other devices. You can also get an input string or filename from the user and store it in the environment but that command is most naturally described in detail in the next chapter. (see Sections V.4 and V.5). You can have BATUTIL pop up a menu of choices: you can have up to 16 choices - if you try more, BATUTIL will exit with an errorlevel over 200 set (and an error message if verbose mode is on). Each choice can be up to 60 characters long (after metastring translation). If the string is longer, then it is truncated at 60 characters. The syntax is batutil {MEnu choice1 choice2 choice3 ...} Each pair of choices must be separated by a space. If you want a choice to appear with a space in the middle, use $S and rely on metastring translation to turn those into spaces. For example batutil {ME choice$S1 choice$S2 choice$S3} would pop up a menu of the form ╒══════════╕ │ choice 1 │ │ choice 2 │ │ choice 3 │ ╘══════════╛ A highlight appear initially on the top choice and the following keys (plus others - see below) work: <Down>,<Tab>,<Spacebar>,<+> move the cursor down <Up>,<Shift-Tab>,<Backspace>,<-> move it up <Home>,<PgUp> go to the first choice <End>,<PgDn> go to the last choice <Esc> exits and sets the errorlevel to 0 <Enter> makes the highlighted choice If the user picks the nth choice on the menu, the errorlevel is set Chapter IV:USER INPUT Page 54 Documentation for BATUTIL, Version 4.0 to n. In default mode, BATUTIL will look for a Microsoft compatible mouse and, if found, the mouse will work on the menus: moving the mouse up or down will move the highlighting and either mouse button will choose the highlighted item. If you don't want the mouse active in the menus, use the {NMouse} command. The bar wraps around from top to bottom or vice versa. The screen is saved upon menu pop up and restored on pop down. In this version of BATUTIL, you cannot modify the menu colors or the border type. BATUTIL automatically centers the menu on the screen both from left to right and top to bottom. You cannot adjust the position of the menu in this version. BATUTIL gives special treatment to the first capital letter or number in each choice. That symbol will appear in a special highlight and hitting that key will make that choice. For example batutil {Copy Erase reName format eXit} will display a menu with five choices. Hitting upper or lower case C, E, N, X will choose the first, second, third or fifth choice. There is no shortcut choice for "format" since no letter is capitalized. Only the first capitalized letter in each choice counts so that if "Copy" were replaced by "COPY" only the first C would have a unique color and would be the quick key to make that choice. If two different choices have the same capitalized letter, e.g. if "eXit" above were replaced by "Exit", only the first E would have the special color and only the first choice would be made if an <E> were hit. Future versions of BATUTIL may adopt the Windows standard use of & in menu choices so you should avoid the use of the & symbol in your menu choices (although && for & will be supported). Extra options for how menus look and/or choices are made can be found in the third section. The sample batch file MENUDEMO.BAT will display sample menus and studying it should help clarify issues of syntax. IV.2 Getting a Menu from a File Command: FMenu Parameters: filename, optional label as a second parameter Chapter IV:USER INPUT Page 55 Documentation for BATUTIL, Version 4.0 If your menu has many choices or long descriptions, you will have trouble fitting it on a single DOS command line. While suitable use of environmental variables and the $x command can get around that, a special command is provided for reading in a menu from a file. The syntax of the FMenu command is the same as for FEcho and FPretty and is discussed in Sections I.5 and III.5. Leading and trailing spaces will be stripped and blank lines will be ignored. The separate lines will then be viewed as separate lines in the constructed menus. Embedded blanks will be treated as blanks, that is, unlike the MEnu command where blanks must be indicated with the $S command, blanks in FMenu do not require $S (although metastring translation is done so that $S will be interpreted as spaces). If you are reading in a menu from a file, you have the option of associating each menu item with a line of "help text". After listing the menu items, place a line with an @ as the first nonblank character. The rest of that line is ignored, but subsequent lines until the next : line will be regarded as help text. They are associated in order, in a one-one way with menu choices. If there are fewer help lines then menu lines, the final few menu items won't have help text. If there are more help lines than menu items the last few help lines will be ignored. Help text is displayed in the attributes set with the ATtr or MAttr commands and replaced with blanks in that attribute when the menu finishes. IV.3 Menu Options Commands: MHeader, POp, SHadow, FKey Parameters: MHeader takes a text string POp takes a + or S to turn on sound effects There are a number of options you can choose which effect the appearance of menus popped up with the MEnu command and one of them effects which keys work. If you wish you may add two extra lines to the top of the menu with the MHeader command. The first line is a text string that you insert as a parameter to MH - spaces are allowed. The second is a graphic line. The MH command must proceed the ME command. So batutil {MH This is a header}{ME a b c d e} would display a menu in the form Chapter IV:USER INPUT Page 56 Documentation for BATUTIL, Version 4.0 ╒══════════════════╕ │ This is a header │ ├──────────────────┤ │ a │ │ b │ │ c │ │ d │ │ e │ ╘══════════════════╛ The menu choices are always left justified while the header is centered. You can use $S's to adjust this justification if you wish. A blank MH, i.e. {MH}, will get ignored but {MH $S} would display a blank header. Like menu choices, headers are truncated at 60 characters if they are longer than that after metastring translation. You can have the menu popup with a shadow effect by using the SHadow command. The attributes of the shadow are the ones current set with the AT or MN commands. A typical menu popup command might be set with batutil {AT 30}{CL}{SH}{AT 0}{ME choices.....} The first AT sets the attributes to black on cyan to produce a cyan screen when you CLear the screen. The second AT then sets the attributes used by the shadow (black). You can have the menu visually explode when popping up and implode upon exiting. You turn this effect on with the POp command. POp will take an optional parameter of + or S to also turn on sound effects. Try out MENUDEMO.BAT to see what the effect is. The final option is to turn on function keys with the FKey command so that batutil {FK}{ME choice1 choice2 choice3} will display a menu ╒═════════════╕ │F1 - choice1 │ │F2 - choice2 │ │F3 - choice3 │ ╘═════════════╛ with Fn labels indicated. Now in addition to the other choices, the function keys will make choices as will the number keys. FK will have an effect if your menu has nine or fewer choices. It is ignored if the menu has more choices than that. Chapter IV:USER INPUT Page 57 Documentation for BATUTIL, Version 4.0 If you try to use multiple menus in a single running of BATUTIL, the options are all reset by the first menu displayed so that, for example the INclude code MH hi! FK ME a b c d ..misc BATUTIL commands ME 1 2 3 4} would display a header and function keys on the first menu but not the second. If the final option in an ME list is of the form the word WAIT followed by a number with NO spaces between WAIT and the number then that choice is not displayed but regarded as a time out in seconds. After the menu is up for that time without a choice being made, the menu will disappear and the errorlevel/RC will be set to the number of the WAIT option. WA and WAI are also acceptable and are not case sensitive. For example {ME Copy Erase Format eXit WA10} would exit with return code 5 after 10 seconds. We recommend that the timeout value you use be a long time - typically 60 or more. But do not use WAITs over 8000. IV.4 GEtkey Basics Command: GEtkey Parameters: list of "keys" separated by spaces, commas or semicolons For many purposes where you want single key input, the MEnu command will be best but that is certainly overkill when you really want to ask something like Backup text files (Y/N)? where a simple <y> or <n> will suffice. The GEtkey command is intended for these situations. In its simplest form, the GEtkey command is followed by a set of "keys" separated by one of space, comma or semicolon (mixed choices are allowed) in the form: batutil [GEtkey key1 key2 ....] where the syntax for allowed keys will be discussed below. BATUTIL will then wait patiently for the user to hit one of the keys in the list and then exit with the errorlevel set to n if choice n was made. For example batutil [GEtkey y n] would wait patiently for one of y,Y,n,N and set the errorlevel to 1 Chapter IV:USER INPUT Page 58 Documentation for BATUTIL, Version 4.0 if y or Y were picked and 2 if n or N were picked. By default, the keys are not case sensitive so that as above y or Y will work. Also, by default, BATUTIL will flush the keyboard buffer before getting a keystroke. BATUTIL will also echo the choice made to give the user feedback and by default will display nothing in response to a key not corresponding to any choice. However, these defaults, including whether there is any visible echo, can be changed as we'll explain in the next section. The maximum number of keys that can be listed is 40. BATUTIL doesn't mind if a key is repeated in the list of keys but it will report the first match so that batutil [GE Y Y y n n y y n] would return errorlevel 1 with a y or Y and errorlevel 4 with an n or N. Unlike STACKEY, BATUTIL does not distinguish between the grey plus and the top row plus nor between the top row numbers and the number pad numbers. Here are the possible choices for keyn in the basic syntax (the two letter codes are essentially those recognized by STACKEY with exceptions like G+ as described above, and the fact that this version does not support keys special to the enhanced keyboard.) - any single ASCII character with some exceptions given below - # followed by any number from 0 to 255 indicating precisely that ASCII code (there must be no spaces between the # and the number) - F1,..,F0; S1,..,S0; A1,..,A0; C1,..,C0 for the 40 function keys as in STACKEY - ^ followed by any upper or lower case letter for the control-character, e.g. ^B for <Ctrl-B> - ^ followed by one of [ \ ] ^ _ for those special ASCII codes, e.g. ^[ for <Esc> - ^1, ^3, ^4, ^6, ^7, ^9 for <Ctrl-End>...<Ctrl-PgUp> as in STACKEY - @ followed by an alphabetic letter, number, -, _, + or = indicated the Alt-combination as in STACKEY, e.g. @A for <Alt-A> - The following two letter codes which have the same meaning as in STACKEY: FF, ST, SP, SQ, CB, CR, LA, Chapter IV:USER INPUT Page 59 Documentation for BATUTIL, Version 4.0 RA, UA, DA, TA, ES, TB, BT, BS, LF, DQ, IN, DE, HM, EN, PU, PD; for example ES for <esc>. The following ASCII codes cannot be used as a single code because they have special meaning to DOS or to BATUTIL: ASCII code (symbol in paren) │ Use instead ─────────────────────────────────────┼───────────────────── #13 (carriage return) │ #13, CR, ^M #10 (line feed) │ #10, LF, ^J > │ #62 < │ #60 | │ #124 % │ #37 #26 (control Z) │ #26, ^Z { │ #123 } │ #125 [ │ #81 ] │ #83 , │ #44 <space> │ #32, SP ; │ #59 IV.5 GEtkey Options Commands: NFlush, CSent, VIsual, ATtribute Metastring: $L Parameters: For VI - A,1,N,D,DA,D1,DN For AT - Tmn with m,n integers Extra GEtkey parameters: in first place WAitnn for wait in first place WAitEnn for wait with Echo in last place BEep or ELse GEtkey has various extra options to make it more flexible. While it is normally case insensitive, by preceding it with CSent, it will become case sensitive. For example batutil {CS}{GE Y N} would only accept Y and N and not y or n. Similarly, NFlush will avoid the default behavior which is to flush the keyboard before getting a keystroke. You can adjust the visible feedback that GEtkey gives with the VIsual command. This command takes a parameter which tells it what Chapter IV:USER INPUT Page 60 Documentation for BATUTIL, Version 4.0 to do. The choices are the following: The default which echoes the choice the user makes as written in the GEtkey command line, e.g. if you use batutil {GE Y #78} (N is ASCII 78) and the user picks N, then "#78" is echoed 1 which will only echo 1 character choices, e.g. with the above example, Y would get echoed but not #78 N which suppresses the visual echo (N for No) A which provides an echo for all user responses: if the choice is not one on the list a character plus a ? appears. For alphanumeric characters, the character itself is used. For all other keys an upside down question mark appears as the first character. The incorrect choice indicator is erased each time a new choice is made. By default, BATUTIL inserts a space before echoing a response so that a Y response to batutil {EC Are you sure(Y/N)?}{GE Y N} would appear on the screen as: Are you sure(Y/N)? Y with a space after the question mark. If you Don't want this space use a D in the visual command. You can combine the D parameter with another one so long as you place the D first and place no space after it. Thus batutil {VI da}{GE Y N} would provide an echo to all choices with no leading space. In addition, the GEtkey command itself has extra options for parameters other than a list of keys. The last "key" in the list can be one of the key words BEep or ELse (as usual, two letter truncations are allowed). If the keyword BEep occurs, then the user is beeped for every wrong key picked. PLEASE use this sparingly. We hate programs that beep too much and offer it with some misgivings. Be careful since batutil {GE BE} will do a pretty good imitation of a machine that has crashed (^Break will get you out). If the keyword ELse occurs as the last "key", then rather than wait patiently for a key on the list to be hit, BATUTIL will exit with any key hit. If the key is not on the list then the errorlevel is set to the position of the word "else"; for example batutil {GE y n else} Chapter IV:USER INPUT Page 61 Documentation for BATUTIL, Version 4.0 would return errorlevel 1 if y or Y is hit, 2 if n or N is hit and 3 for any other key. If ELse is used a VIsual level of A is ignored. The final option concerns the first "key" on the list which can be WAit followed without any spaces by a number, N, from 1 up to over 8,000 (you will not get an error over 8000 but the response will not be what you expect) or followed by the letter E and a number. BATUTIL will then not wait patiently for a key to be struck but after approximately N seconds, it will exit with an errorlevel of 0 if no other choice is made. Thus two lines in a batch file like batutil {GE WA3 y n} if errorlevel 2 goto No would have the effect of choosing a default choice of Y if no key is struck for 3 seconds. The letter E between the number and WAit tells BATUTIL to echo the first choice on the list if the exit is due to a timeout. This is for use in examples like the above where the timeout choice will pick a default. To get the visual feedback for timeout in the above you'd use {GE WAE3 y n}. There is a system dependent end effect involving the time to load BATUTIL so that WA1 is likely to be anywhere between 1/2 and 2 seconds and WA10 will be between 8 and 12 seconds. In addition, if you start with the GEtkey list with a WAit and end with a BEep and the user holds down the wrong key, then the time before (merciful) exit will be longer than you asked for because beeping takes a considerable amount of time and is not included in the count down time. There may be times that you'll want to visually count down the remaining time. BATUTIL stores two internal parameters called the timerow and timecolumn, initially set to zero. If both numbers have no zero values than a countdown will take place with numbers in the row numbered timerow and beginning in column number timecolumn. There are two ways to change these two parameters. The ROw and COl commands can take the form {RO Ty}{CO Tx} to change these parameters to the numbers y and x. y must lie in the range 1 to the screen height and x in the range 1 to the screen width. Secondly, if you use $L (L for Location) in an ECho or PRetty command, nothing is displayed for the $L but timerow and timecolumn are set to the current cursor position so Chapter IV:USER INPUT Page 62 Documentation for BATUTIL, Version 4.0 batutil {EC Time left: $L seconds}{GE WA60} will work the way that you'd expect. Notice that there are three spaces after the $L - two for the numbers 59,.... which will appear and one for a space before the word. There are two additional parameters that you can use with GEtkey WAit and this display. They are set with {AT Tmn} where m defaults to 3 and n to 4. m can be from 0 to 3 (the 0 need not be explicit) and adjusts how much is the time is offset. To take into account the time to load BATUTIL, GEtkey WAits actually subtracts 3/4 of a second off from the time counted so if you ask to count from 60, the time will start at 59. The wait is m/4 seconds if you set m. In addition, you can change the number counted with n. Time is counted down in units of n times 1/4 second with n between 1 and 8. So n=2 is half second and n=8 is 2 second pauses. The countdown is in this unit BUT the number set after {GEtkey WAit} is always interpreted as seconds. IV.6 AScii, SCanread Commands: AScii, SCanread Every keystroke returns a "scan code" and an ASCII code - these are the int 16 codes as discussed in Section VI.1 of the STACKEY documentation. The commands {SC} and {AS} wait for the next key to be pressed and return respectively the scan code or ASCII part. They are sensitive to the prior use of NFlush. That is, by default, the keyboard buffer is flushed before reading but a prior use of {NF} can suppress the buffer flushing. SCan codes are always smaller than 128 but ASCII codes could be above 200. This command is one of only two commands that can return an errorlevel above 200 without indicating an error (the other one is the RUn command). IV.7 Username/Password Checking Command: USername Parameters: sequence of names; first one can be a number of tries; second can be * You may have a batch file which you want to branch depending on what "username" the user enters. This is what the USername command is for. The simplest syntax is Chapter IV:USER INPUT Page 63 Documentation for BATUTIL, Version 4.0 batutil {US name1 name2 name3 ....} with names separated by spaces. The names cannot have more than one word since metastring translation does NOT take place. BATUTIL will display an edit box preceded by ===> which allows entry of a name up to 20 characters. The usual edit keys work. After the user presses <Enter>, the string entered is compared with the list of names - if there is a match with the Nth name on the list, an errorlevel of N is returned. Otherwise an error level of 0 is returned. As an option, the first parameter can be a number. In that case, that number indicates an additional number of tries which are allowed. If N is 3 or more, and the first entry isn't a match, BATUTIL will beep and display the message: Please try again ===> When there is only one try left, (and in particular if N=2 after the first try), the message Only one more try ===> will appear. There is another special and VERY DANGEROUS option to be used with care. If the first parameter is a number and the second parameter is a * as in batutil {US 1 * abc def} then if the number of chances is exhausted, rather than return an error level of 0, BATUTIL will respond Invalid! System halted and go into a tight loop. This is a very crude security measure since even if you place it in your autoexec.bat, booting from a floppy can give an intruder access to your system. But it will be effective against an unsophisticated but nosy intruder. When either the number or number and * options are used, the numbering of choices is counted starting after these optional special parameters. That is, in the last example, "abc" would set an errorlevel of 1 and "def" an errorlevel of 2. By default, USername is not case sensitive and flushes the buffer before asking for input but either of these can be changed by a prior use of {CS} or {NF} as described in Section IV.4. IV.8 Parameter Matching Command: PMatch Parameters: list of words Chapter IV:USER INPUT Page 64 Documentation for BATUTIL, Version 4.0 The PMatch command is followed by a list of words as in batutil {PM word0 word1 ....} It checks word0 against each of word1, .... If there is a match first with wordN the error level is set to N, otherwise to 0. This is typically used to check for errors in batch file parameters. For example if allowed parameters are "comp" and "bold", you could use echo off batutil {PM %1 comp bold} if errorlevel 1 goto %1 echo %1 is not a valid choice; use COMP or BOLD goto end :comp LINES for comp goto end :bold LINES for bold :end This has several advantages over the more usual sequence of if %1 == bold goto bold First, it is only one command. Secondly, because labels are not case sensitive, you can use "goto %1" to handle all the different, Bold, BOLD, etc. cases. By default, PM is not case sensitive but you can make it so with the {CS} command if you wish. IV.9 Querying the Lock Status Command: QLock Parameter: first is C, S, N or I; second (optional) is + or - If you have a long autoexec.bat file which branches in the middle, you may want to set it up with a Y/N question which uses GEtkey with the WA parameter to pick a default choice. But suppose you don't want the default choice. Is there any way to overrule the default without waiting around for the Y/N question to appear? The QLock command is precisely made for such situations. It will read the status of CapsLock or NumLock or etc. and return it in the errorlevel. So you could test for the CapsLock as an antidote to the automatic yes. We'll describe an example of this in Section VI.3. QLock takes one mandatory parameter and one optional one. The mandatory one determines which lock will get queried; the Chapter IV:USER INPUT Page 65 Documentation for BATUTIL, Version 4.0 choices are C, S, N and I for CapsLock, ScrollLock, NumLock and Insert. Thus batutil [QL C] will test the state of CapsLock and set the errorlevel to 1 if it is on and 0 if it is off. The optional parameter is a + (resp. -) which makes sure that the lock state is left on (resp. off) when BATUTIL is done. For example batutil [QL C -] would read the lock state but make sure that it was off when the process was done. Chapter IV:USER INPUT Page 66 Chapter V:ENVIRONMENTAL CONTROL V.1 Environmental Impact Statement DOS keeps an area of memory called the active environment where it stores the information that you put in your PROMPT and PATH commands and where it stores the location of the file command.com. In addition, some programs ask you to store information there which you place with the SET command. Because the DOS command line is limited to 127 characters, you are unable with DOS tools to have a prompt string over 120 characters (127 minus the length of "prompt=") nor a path over 122 characters. The syntax of the set command is set foo=string and we will refer to "foo" as the variable name and "string" as the value of foo. Programs, when they load, are given a copy of this active environment and it is this copy that they are supposed to consult or modify. The location of the active environment is undocumented and programs are not "supposed" to access it. Batch files can access the environment - if the string %foo% appears anywhere in a batch file, DOS looks for a variable "foo" in the active environment and if it finds it, then %foo% is replaced by this string. If there is not a variable named foo, then %foo% is replaced by the empty string. This %foo%, which only works in batch files, was undocumented until DOS 3.3 but has worked in all versions of DOS. BATUTIL gives you considerable control over the active environment including the following: - you can query the user and have the answered stored in the environment - You can have environmental strings up to 255 characters rather than the DOS 127 character limit and, in particular, your PATH can be up to 250 characters and your PROMPT up to 248 - you can add or delete directories from your path. - you can get a more informative report of what is in your environment than what DOS supplies with the SET command - you can call up an editor to edit by hand the path or the environment as a whole - you can save the current environment to a file and later reload it. Chapter V:ENVIRONMENTAL CONTROL Page 67 Documentation for BATUTIL, Version 4.0 !!!WARNING!!! BATUTIL can do these things by directly accessing the DOS active environment which violates the general guidelines for "well behaved" programs and uses undocumented features. We have extensively tested these things with many versions of DOS and we feel that these actions are safe BUT you use these undocumented commands at your own risk. BATUTIL has certain safeguards built in so that it will exit with an error code if it doesn't find an appropriate candidate for the environment so it should be safe but CTRLALT Associates cannot be responsible for any problems caused by your willingness to use our attempt at giving you improved performance by mildly violating the rules. Early versions of DRDOS 5.0 were incompatible with BATUTIL because of the environment handling. But this is not a problem with later version of DRDOS 5.0 and with DRDOS 6.0 so long as a shell of DR DOS isn't run. All version of MSDOS to date are compatible with BATUTIL with or without a shell. DOS' treatment of the environment has varied from version to version and while we have tested it under DOS 2.0 thru 5.0, there is a chance that we will not find the proper environment under future versions of DOS. In addition we have tested running with a path over 122 characters in length and DOS seems to behave perfectly. However, an application program might get unhappy at finding a path over what it regards as the theoretical maximum. Indeed, Flambeaux Software's TechHelp!! crashes while loading with a path of more than 122 characters and 1986 versions of PKXARC behave erratically with a long path. IMPORTANT NOTES: DOS' SET command only displays the first 128 characters in each environmental string. You may think that BATUTIL has failed to increase your path beyond 128 bytes if you just try set, but the full path will work. Use batutil {EN} to get a full report of all the strings of any length up to 255 bytes. If you use another program to get environmental strings over 255 bytes in length, BATUTIL will refuse to load. If you need strings over 255 bytes, let us know and BATUTIL may support them in a future version. Especially with the extra capability that BATUTIL gives you, you may find the 160 character default environment provided by DOS is too small. You can get around this in two ways: DOS 3.1 has an undocumented option and DOS 3.2/3.3/4.0/5.0 a documented option to change the environment with the following command Chapter V:ENVIRONMENTAL CONTROL Page 68 Documentation for BATUTIL, Version 4.0 in your CONFIG.SYS: shell=C:\command.com /P /E:xxxx where C:\ can be replaced by whatever path points to command.com and xxxx is the number of bytes you want in the environment under DOS 3.2-5.0 and it is the number of 16 byte units under DOS 3.1. Thus for a 512 byte environment you'd replace xxxx by 512 under DOS 3.2-5.0 and by 32 under DOS 3.1. The second method which you'll need under DOS versions prior to DOS 3.1 is to patch command.com. Information for such patches is available on many bulletin board systems. SHELLs under DOS 3.2 and later can have enlarged environments. Just use command /e:xxxx where xxxx is the number of bytes that you want environment in the shell of DOS to have. Softlogic's Software Carousel sets up a larger environment in its partitions than you specified in a shell command in your config.sys and since BATUTIL reflects reality, it will report this larger environment size. JP Software's 4DOS program in certain modes INCLUDING the default for Version 2.1 will not work with BATUTIL. Instead BATUTIL will exit with an error message. In order for BATUTIL to work with 4DOS you must: - have Version 3.00 or later of 4DOS - or a Version after 2.10 and you load 4DOS with the /M:xxxx (where xxxx is the desired environment size) switch In addition, be warned that there is a special problem that arises if you try to run 4DOS and BATUTIL together on a system whose underlying DOS version is 3.2. If you load a shell of 4DOS (perhaps as the base command processor) and then load a shell of command.com, BATUTIL will not change the active DOS environment but another memory area. No harm will be done but you will not effect the path or other DOS variables in this rather special circumstance. V.2 Environment Reports Command: ENvrep Chapter V:ENVIRONMENTAL CONTROL Page 69 Documentation for BATUTIL, Version 4.0 The command batutil {ENvrep} will display a listing of all environmental strings as DOS' SET command does but it will also list the following: - the length of each environmental string - the total size and amount of free space in the environment - the location of the active environment V.3 SEt Basics Command: SEt Parameters: var1=string1 var2=string2 (separated by spaces) BATUTIL has a SEt command that lets you place variables into the environment. The syntax is batutil {SE foo1=string1 foo2=string2 ...} You can enter more than one string at a time (although one string is also allowed). Distinct strings are separated by spaces. If any string is missing an = sign, BATUTIL will exit with an errorlevel of 208 (and issues a message if you are in Verbose mode). If you want to place a space into the value of one of the strings, use $S which will get translated into a space. "But", you say, "DOS' SET lets me put strings in the environment, so why do I need BATUTIL." Often DOS is the way to go but BATUTIL's SEt has the following advantages: - You can place more than one variable into the environment at a time - BATUTIL does metastring translation so that you could use something like batutil {SE today=$E} to get today's date in English into the environment or if you want Ctrl-Z as part of your prompt string (the right pointing arrow is an interesting alternative to the more usual greater than sign), then you'll have trouble doing that from a batch file but the pair of symbols ^ and Z in a BATUTIL SEt will work, e.g. batutil {SE prompt=$$p)^z} - You can use SEt to get variable values of length over 127 characters into the environment (see below). As with DOS' set command, {SE foo=} with no string after "foo=" will remove any variable named "foo" from the environment. Chapter V:ENVIRONMENTAL CONTROL Page 70 Documentation for BATUTIL, Version 4.0 Because of the metastring translation, you'll need to exercise some care when using prompt strings. For example, if your prompt were $t$_$p$g which displays the time and then on a second line the path and a '>', and you decided to add the date and used batutil {SE prompt=$d;$X(prompt)} you'd not get what you wanted. The $d would get translated into today's date (which wouldn't be bad although it would waste environment space) but the $t and $p would get "evaluated" and would no longer change as you the time changed or you changed directory. Instead you should use batutil {SE prompt=$$d;$x(prompt)} (recall that $X does metastring translation while $x does not). Careful use of $x, $$ and occasional use of the {$T - } will avoid problems but care is needed. DOS is limited to 127 characters on a command line and it does %foo% translations at a point where that limitation is still in effect so that if your path has 120 characters and you use the DOS command set path=%path%;C:\bin; in a batch file, DOS will expand the %path% and crowd all but the ";C" off the line. But BATUTIL only does the translation later and allows environmental strings up to 255 characters so that batutil {SE path=$x(path);C:\bin;} would work perfectly - it is with the use of the $x command that you can get environment strings over 127 characters (as well as with the ADdpath and LOadenv) commands. Actually, you wouldn't want to use the above command line - adding to your path is sufficiently important that it is a primitive BATUTIL command and you'd use: batutil {AD C:\bin} V.4 Internal Variables and Hacker Mode Commands: $1,...$9,$é,...$ò, ++, -- While the SEt command will normally set an environmental variable, there are two sets of exceptions where special values of the variable, var, in var=value will set something else: internal variables and hacker mode pokes. Chapter V:ENVIRONMENTAL CONTROL Page 71 Documentation for BATUTIL, Version 4.0 BATUTIL has 32 internal variables of which 30 can be set by the user. These variables are discussed in Section VI.1. The basic syntax is SEt $1=value Metastring translations of 'value' are as in the ordinary SEt command, the only difference being that instead of placing the value in the environment preceded by $1=, it is stored internally by BATUTIL. You can set multiple internal variables in a single set command or mixed internal and environmental variables. If a command starts with $1, etc., an implied SET is added before it so that $1=$E foo=bar is equivalent to SEt $1=$E foo=bar Note it is important to have no space between the $1 and the =. ++ and -- are shorthand for incrementing/decrementing an internal or environmental variable. That is ++$1 is the same as ($V is discussed in Section VI.3) SEt $1=$V($1+1) and similarly for --$1 and $V($1-1). If ++ is followed by any string other than the thirty internal variables, it is treated as an environmental variable so that, for example ++ foo translates to SEt foo=$V($x(foo)+1) Notice that if $1 is empty to start with $V($1+1) becomes $V(+1) which is 1 so empty variables act like a 0 under ++ or --. In the SEt command $Z and $z for the value of variable have a special effect and do not set environmental variables. See Section VI.13. V.5 Getting User Strings into the Environment Commands: ?Length, ?Size, LEngth, QUery Parameters: ?L takes a number from 1 to 255 ?S takes a number from 1 to 80 LE takes a string QU takes - Metastrings: $Q, $?, $¿, $N Chapter V:ENVIRONMENTAL CONTROL Page 72 Documentation for BATUTIL, Version 4.0 As part of the set command, you can query the user for a string to be placed into the environment. The metastrings $Q and $? are used with slightly different display possibilities. Do not confuse $q (the prompt metastring for the character =) and $Q, the Query command. The usual form that you'll use is batutil {SE foo=$Q} or batutil {SE foo=$?} although there is no reason that $Q or $? couldn't be part of a complex string. Only one $Q or $? will be translated per string so that batutil {SE foo=$Q$Q$?} would Query the user and append the characters "$Q$?" to the end of the input. But multiple strings each with its own query are in principle possible so that batutil {SE foo1=$Q foo2=$Q} would query the user twice. You will need to place an appropriate prompt on the screen to indicate to the user what you expect as in batutil {EC Enter filename to use$_}{SE foo=$Q} or batutil {EC Enter two filenames to use$_}{SE foo1=$Q foo2=$Q} With the $Q command, the BATUTIL adds it own prompt of ===> in distinctive colors (yellow on black on a color monitor) and then displays an edit box in reverse video on a monochrome screen and yellow on green on a color monitor. The edit box is 50 columns wide and the maximum string length that can be entered is 80 characters (with horizontal scrolling as described in Section I.7). These can be adjusted with the ?L and ?S commands as we'll describe. All the editing commands discussed in Section I.7 are active. The $? gives you more control over the display but at the "cost" of more effort on your part. You can customize your own prompt. Rather than use a fixed set of attributes, the AT and MN attributes are used to determine the colors of the edit window. For example, to duplicate batutil {SE foo=$Q} you'd use batutil {AT 0E}{EC ===$g$S}{AT 2E}{MN 70}{SE foo=$?} Of course, you would not do this to duplicate $Q but you can adjust Chapter V:ENVIRONMENTAL CONTROL Page 73 Documentation for BATUTIL, Version 4.0 colors and prompts in this way. The {$T -} command does NOT turn off $Q/$? expansion. Rather you can turn this off independently of the state of $T with the QUery command: {QU -} would turn it off and {QU +} will turn it back on. While the default maximum length of input for the $Q and $? commands is 80 characters, you can adjust this with the ?L command. Similarly, the ?S command effects the size of the edit window. Thus batutil {?L 30}{?S 5}{SEt foo=$Q} would give a small 5 character window scrolling to support a 30 character input. The ?S command takes a value between 1 and 80 - any other value will cause BATUTIL to exit with a syntax error. With window sizes that are close to maximum value (or if you have moved the cursor prior to calling {SE foo=$?}), the edit window may wrap to the next line. ?L will take values from 1 to 255. If ?L is smaller than ?S then BATUTIL automatically adjust ?S down to the size of ?L. If you want to know the length of a string input by the user or which you'll need for some other reason [LEngth string] will return that length after metastring translation unless {$T -} is in effect. An error level of 199 is returned if the string is 199 characters or more in length. Normally, LE is used with something requiring metastring translation, especially a $x variable. The LE command is kept for compatibility. With BATUTIL 4.x, you can also get the length of a string with a $s command - see Section VI.2. The metastring $¿ (that's $ followed by ASCII 168) is just like $? except that what you type in is not echoed to the screen. This makes it suitable for password entry. In addition to string input, you can force numeric input with $N. The number will be between -1,000,000,000 and 1,000,000,000. The default is 0. Chapter V:ENVIRONMENTAL CONTROL Page 74 Documentation for BATUTIL, Version 4.0 V.6 Using the File Pick List Metastrings: $F,$f BATUTIL lets you popup a file list from which the user can choose a file and you can have the filename chosen saved in the environment. Within the set command, just use a $f or $F on the right side of an equal sign and a file list will popup. Arrows move the bar cursor by one space <PgUp> <PgDn> move up/down by one panel of 22 files <Home> <End> move to the first/last file The list end with a listing of subdirectories and drives. Hitting enter on a subdirectory will cause that subdirectory to be displayed and on a drive letter, will shift the display to the current directory on that drive. Files show in lowercase, directories in uppercase and drives surrounded by [- -]. Included in the list unless you are already in the root are, the parent directory indicated as ..\. <Enter> chooses that file and fills its full pathname in place of the $f. The directory is stored in the variable FDIR with the provisos discussed in Section II.6. <Esc> exits with $f and FDIR replaced by the empty string. If the user exits with <Enter>, RC is set to 0 and if with <Esc> to 2. Optionally, you can place a filespec in parentheses immediately after $f as in $f(A:d*.*) The filelist will then only list matching files. All subdirectories and drives are listed. Even if the drive or directory is illegal (for example a floppy without a disk or free drive letter!), the other legal disk drives will be listed to allow switching to them. The filespec appears at the top of filelist box. A scroll bar appears on the left of the filelist box and the slider shows the fraction of the list of the current cursor. In this version, a mouse is supported with the filelist. A separate mouse cursor will appear if you have a mouse and {NMouse} hasn't been set. The right button acts like <Esc>. Left click on the list moves the cursor there and double left click moves and issues an <Enter>. Metastring processing is done inside $f primarily to allow for the use of $x. Thus the following works as you'd expect: batutil {EC Enter filespec}{SEt foo=$Q foo=$f($x(foo))} Chapter V:ENVIRONMENTAL CONTROL Page 75 Documentation for BATUTIL, Version 4.0 Only the first $f is expanded on the right side of an equal sign. However, within a single set command, $f's associated with distinct variables will each be processed. While this capability is there, we recommend against normally using it as the user can get confused about there really being several commands. $f has changed some from Version 1.0 as we refine some design decisions. Rather than exit with an error set for an illegal drive or file spec in (..), we show all valid drives. Rather than use letters to switch, they appear on the file list much in the format of Windows. V.7 Saving and Loading the Environment to a File Commands: SAvenv, LOadenv, KIllenv Parameters: SAvenv and LOadenv take a filename with LOad allowing an extra /m to merge; KIllenv takes a list of variables to keep BATUTIL allows you to do automated bulk operations to the environment: - {SAvenv filename} will save a copy of the environment in the file "filename". If the file already exists, you will asked confirmation to overwrite. If the user responds N, then the error level is set to 199. - {LOadenv filename} and {LOad filename /m} will load a previously saved environment. The first command will completely replace the environment with the one in the file saving nothing from the prior environment. The command with the /m will merge the saved environment with the current environment - variables which are in the current environment but not in the saved environment will be kept. Variables which occur in both the current and saved environment will be assigned the value in the filename. - {KIllenv} will remove all strings from the current environment except for the COMSPEC string which BATUTIL will not remove (if you insist on removing it, use SET comspec= as a DOS command). In addition you can save some specific environmental variables by including their names as parameters. For example batutil {KI path prompt} Chapter V:ENVIRONMENTAL CONTROL Page 76 Documentation for BATUTIL, Version 4.0 would remove all non-DOS variables from the environment. The environment saved by the {SA} command is saved as an ASCII file with one variable per line. You can edit it with any ASCII editor that will support lines which are long enough. You can freely add lines but no line should have over 255 characters. Any line added must have the form VARNAME=value (without leading blanks) where VARNAME is all caps, and value is not an empty string. The KIllenv command is intended for use in third party batch files if used with care (but see below). You can save the user's environment to a file, use KIllenv and later load the saved environment. You can then use the environment for variable space while your batch file runs. It is recommended that if you do this, you exercise several cautions: - check for sufficient space without killing the environment and if there is sufficient space, don't save and kill. You could also consider checking if the user has DOS 3.2 or later and get the larger environment by using command /c /e:1024 to rerun the batch file with a larger environment - warn the user what you are about to do and give them the option of aborting the batch file. - be sure to use SA and KI in the same command line as in batutil {SA foo1}{KI} since a file error during the save operation will halt BATUTIL and so the KI command won't happen if the SA doesn't work. Also, BATUTIL halts if the file exists and the user says not to overwrite. Check for errorlevel 199 - Be sure to erase the saved environment file when your batch file ends to avoid giving the user a file he/she knows nothing about and to avoid problems if your batch file is rerun. - Check for the existence of the filename you want to save for first and give the user more useful information than the general `File exists; Overwrite (Y/N)?' that BATUTIL provides. KIllenv is kept for compatibility and special purposes. Normally where you might want to use KIllenv with Version 1.0, you can instead use a combination of the {RC $} command and internal variables. Chapter V:ENVIRONMENTAL CONTROL Page 77 Documentation for BATUTIL, Version 4.0 V.8 Batch File Path Control Commands: ADdpath, DElpath Parameters: list of paths separated by space, comma or semicolon - $p and $P are processed BATUTIL will let you easily add additional directories to your DOS search path and delete directories. The syntax is batutil {AD dir1 dir2 ...} batutil {DE dir1 dir2 ...} The keyword ADdpath or DElpath and the directories in the list may be separated from one another by any combination of spaces, semicolons, and commas. ADdpath can be compared with what you can do in a DOS batch file by saying set path=%path%dir1;dir2; ADdpath allows paths over 127 characters (actually, if you really want a path over 127 characters, you should consider changing your disk setup - too many directory entries in a path will slow DOS down), the $p,$P translation as discussed below and it won't let you duplicate an entry in the path list (so long as you don't try to do something like C:\bin and \bin which it will allow). DElpath will search the path and remove the specified directories if found in the path. The string listed in the command must agree (except for case) with a directory name in the path. ADdpath and DElpath do not do metastring translation except for $p and $P. For example, the following batch files would add and subtract the current directory from the DOS path addpath.bat batutil {AD $p} delpath.bat batutil {DE $p} A typical application of these commands would be if a program silly.com requires that its directory C:\rudeprog be in the path when it is run. A batch file to do this would read: batutil {AD C:\rudeprog} C:\rudeprog\silly batutil {DE C:\rudeprog} Chapter V:ENVIRONMENTAL CONTROL Page 78 Documentation for BATUTIL, Version 4.0 BATUTIL has no problem reading in paths which don't end with a semicolon but the paths that it writes out always have a semicolon at the end. The AD and DE commands return information in the errorlevel and/or variable RC. AD tells you the number of directories actually added to the path (since entries are not duplicated, this may be smaller than the number listed) and DE the number deleted (since you may have listed a directory not in the path, this may be smaller the number listed). V.9 Direct Editing of the Path Command: PAthedit, NBeep batutil {PAthedit} brings up an interactive editor which allows you to edit your path. Up to 17 directories can be displayed at once; with more, you can use the arrow keys to scroll or PgUp/PgDn to move by 10 directories at a time. One of the directories is highlighted. <Up>, <Down>, <Home>, <End> do the obvious thing to the highlight. <Enter> picks out that entry and lets you edit it using the line editor discussed in Section I.5. Ctrl-D will delete the directory the cursor is on from the path list (but not change the actually on disk directory) and Ctrl- A will let you add a new path. The order of the directories in your path matters somewhat in that DOS searches in the specified order (in particular, if you have a RAM disk, put its directories before the any others). Alt-T moves the highlighted directory to the Top of the list and Alt-B to the Bottom. All these changes only effect the in memory copy of the path but not the true path as stored in the environment. When you press <Esc> to exit, if you have made any changes, then BATUTIL will offer to save them to the true path as stored in the DOS environment. There are various places that BATUTIL will beep and display a message to warn you; for example, when you exit and are asked if you want to save the edited environment. If you don't like beeps, the NBeep command will turn off the beeps for the PAthedit and EDitenv commands. You could call up the PAthedit command with batutil {NB}{PA} Chapter V:ENVIRONMENTAL CONTROL Page 79 Documentation for BATUTIL, Version 4.0 or can place {NB} in the BATUTIL environment string. V.10 Direct Editing of the Environment Command: EDitenv Parameter: optional name or $ batutil {EDitenv} brings up an edit module for the full environment very similar to that discussed in the last section. The main difference are the following: - Total and free environment space is listed on the bottom line - Only the first 80 characters of each environment string is displayed - Each environmental variable has two pieces: the name of the variable and its value stored as name=value <Enter> allows you to edit the value while ^<Enter> the name. While Ctrl-T/B are active, the order of variables in the environment does not normally make any difference. You can also follow ED with a single variable name. If the variable is in the environment, that value is brought into the line editor for editing. If it is a new variable you get to use the line editor to define it. NBeep applies to this module also. You are limited to editing environments with no more than 511 strings (each with no more than 255 bytes). The command {EDitenv $} brings up an interactive editor for BATUTIL's 32 internal variables. Chapter V:ENVIRONMENTAL CONTROL Page 80 Chapter VI:BUSIC VI.1 Internal Variables Commands: PUt, RC, $1,..,$0,$é,..,$ò (implied SEt) Parameters: PUt takes + or -. RC takes $ or nothing. Metastrings: $1,..,$0,$é,..,$ò,$r,$% BATUTIL includes a full blown language for manipulating your 'batch' files. In essence, since these commands are to BATUTIL and not DOS' batch processor, they aren't in batch files although careful use of the INclude command as explained in Section I.7 will allow you to place them in your .bat file. We've dubbed the language BUSIC for BatUtil's Standard Instructions and Commands. In this section, we'll describe the internal variables which supplement the use of the environment and in the next three manipulation of strings, numbers and dates via metastring translation. Section VI.5 deals with reading and writing files and VI.6-VI.10 with the reserved words in the language. Section VI.11 describes the internals of the how the language is interpreted to help you understand some of the output of the trace command described in Section VI.12. Section VI.13 isn't really about the language but rather about peeks and pokes to memory and ports, a subject we thought of interest mainly to the same users who wanted to deal with advanced aspects of BUSIC. BATUTIL understands 32 internal variables of which 30 are user modifiable. They are denoted $1,...,$9,$0 for the ten you'll use commonly and 20 which are $ followed by an ASCII character from 130 to 149. These characters can be entered in many editors by holding done the Alt key and typing the three numbers on the keypad. They'll appear on screen as é,â,ä,à,å,ç,ê,ë,è,ï,î,ì,Ä,Å,É,æ,Æ,ô,ö,ò so for example $å is the variable associate to ASCII 134. As explained in the last two chapters you can assign values to these variables with the SEt command (or via an implied SEt since any line starting with $ followed by 1,..,0,é,..,ò has an implied SEt added) and you can get out the current value in any string that gets metastring translation such as ECho or the right side of a SEt command. The 31st variable, indicated by $r normally has the last value set by any command that the environmental variable RC; indeed, by default, $r is the same as $x(rc). However, at times you don't want the environment to be used, you can use the command Chapter VI:BUSIC Page 81 Documentation for BATUTIL, Version 4.0 {RC $} which tells BATUTIL that whenever it is about to set the value of RC, it should instead set the internal value stored in $r and then $r references this internal variable. $% stores the first file error found by BATUTIL and is discussed further in Section VI.5. BATUTIL stores the internal variables in its memory while it is running but when it exits and gives up its memory to DOS, the values are gone. To save the values in memory, you need to store them in the environment and recovered them when you next restart BATUTIL. The {PUt +} command places all the non-empty values in the environment so that for example it might add $1=8 $2=foobar and the {PUt -} command looks for such strings in the environment, transfers the values to the internal table and deletes the values from the environment. Note that using $R will change $9 and that the variables $7, $8 and $9 are used a "hidden" parameters for some commands. All these variables are of string type but the string may happen to be one describing a number - see Section VI.3. The maximum length of an string stored in one of these variables is 255 characters. You can interactively edit the internal variables using ED $ VI.2 String Manipulation Metastring: $s(2 to 4 allowed parameters) BATUTIL allows you to manipulate strings of characters with the $s metastring (don't confuse with $S=space). $s must be followed by a ( followed by 2,3 or 4 parameters separated by commas. The first is a single letter which describes the action, the second the string to be analyzed and the final an additional parameter required in some cases. The string in position 2 cannot contain any of the parameters comma, {}[]) but since metastring translation is done you could use that to get such characters in. Normally metastring translations are Chapter VI:BUSIC Page 82 Documentation for BATUTIL, Version 4.0 done on the additional parameters (the exception is the subcommand #). So the syntax is $s(subcommand,string,additional params) Here is a summary of subcommands: Subcommand Purpose Additional parameter(s) U Uppercase NONE L Lowercase NONE S Size NONE P Position substring C Copy start, length D Delete start, length I Insert substring, position W Word word number (0=total) T Trim NONE F Format L,R,C + length # count character Here are the details (the subcommand can be upper or lowercase): $s(U,string) returns the string all uppercase $s(L,string) returns the string all lowercase $s(S,string) returns the number of characters in the string $s(P,string,substring) returns the position of the first location of substring in string (0 if not found) $s(C,string,start,length) returns a string of size length beginning at position start in string (if the string has total size less than start+length-1, then the returned string has length size(string)-start+1) $s(D,string,start,length) returns the string with length characters deleting starting at position start $s(I,string,string1,start) inserts string1 into string with the first character of string1 in position start. $s(W,string,num) returns word number num in string unless num is 0 in which case it returns the number of words in string $s(T,string) returns string with leading and trailing blanks deleted $s(F,string,X,length) with X=L,R or C returns a string of size length or more with string padded with blanks in front and/or back so that string is left/right/center justified $s(#,string,cha) returns the number of times the character cha Chapter VI:BUSIC Page 83 Documentation for BATUTIL, Version 4.0 occurs in string Here are examples. To indicate spaces we will put the result in quotes although they are NOT in the actual returned string: $s(U,Now is the time) becomes "NOW IS THE TIME" $s(L,Now is the time) becomes "now is the time" $s(S,Now is the time) becomes "15" $s(P,Now is the time,ti) becomes "12" $s(C,Now is the time,10,5) becomes "e tim" $s(C,Now is the time,10,25) becomes "e time" $s(D,Now is the time,10,4) becomes "Now is thme" $s(I,Now is the time,hi ,10) becomes "Now is thhi e time" $s(W,Now is the time,3) returns "the" $s(W,Now is the time,0) returns "4" $s(T, Now is the time ) returns "Now is the time" $s(F,Now is the time,L,19) returns "Now is the time " $s(F,Now is the time,R,19) returns " Now is the time" $s(F,Now is the time,C,19) returns " Now is the time " $s(#,Now is the time,i) returns "2" VI.3 Arithmetic Commands: ++, --, ISnum Parameters: $1,...,$0,$é,...,$ò or environmental variable for ++ and -- string or string min max for ISnum Metastring: $V Because BATUTIL does not distinguish between string variables and numeric variables, it needs to know when it sees a + whether you intend it as just a character or an arithmetic operation. When it sees $1+$2 and $1 cannot be interpreted as a number, it can't be sure if it's an error or not. So you must use a special metastring $V (not to be confused with $v=current drive) to indicate arithmetic operations. Whenever BATUTIL finds a $V in a place it does metastring translation (like ECho, SEt, MEnu, etc), it looks for a ( immediately following it and reads to the matching ) and takes the ... in $V(...) and eValuates it (or finds its Value) using the following operations: / integer division, e.g. 15/7 = 2 \ mod (division remainder) e.g. 15\7 = 1 Chapter VI:BUSIC Page 84 Documentation for BATUTIL, Version 4.0 ** power * multiplication + addition - subtraction (also allowed for negative numbers) This ordering describes the order in which it does operations so that, for example, multiplication is done before addition and $V(3+2*4) is 11. BATUTIL understands nested parentheses which can be used to affect the order of precedence so $V((3+2)*4) is 20. BATUTIL only understand integers and never deals with reals or fractions. By integer division, we mean the following: if m and n are both positive, then m/n is that number q so that m = qn + r with r in the set 0,1,2,..,n-1. For general m,n if sgn(x) is the sign of x and |x| is its absolute value then m/n = sgn(m)*sgn(n)*|m|/|n| m\n is the mathematically correct modulo function, so for any m and n, it is the r in 0,1,..,|n|-1 with m = qn + r Note that for general m and it may not be true that m = n*(m/n) + m\n although this is true if m and n are positive. Generally, BATUTIL will exit with a "number too large or syntax error" error message if the initial or final numbers are more than 1,000,000,000 although occasionally numbers up to 2,147,483,647 are allowed without an error message. Other error messages that can occur include: illegal character: Note that a comma as in 1,000 is illegal parenthesis mismatch: for example, $V((2+3*8) spacing error: for example, $V(2 3) but $V(2 + 3) is OK operator missing: for example $V(2(3+4)) illegal negative power division by zero BATUTIL understands two shorthand commands for incrementing or decrementing a number, name ++ and --. ++ XXX is interpreted to mean SEt XXX=$V(XXX+1) if XXX is one of the thirty built in variables. Otherwise it is interpreted to mean SEt XXX=$V($x(XXX)+1) and similarly for --. Chapter VI:BUSIC Page 85 Documentation for BATUTIL, Version 4.0 Because BATUTIL exits if $V encounters a non-numeric string, you may want to be sure that a variable has a numeric value. In addition you may want to be sure that a number falls inside a given range. The ISnum command is intended to check this. The syntax is either ISnum string or ISnum string min max The first command returns a value of 0 if the string is a number within the range -2,147,483,647...2,147,483,647 and 3 otherwise. The second requires that min and max be numbers in this allowed range from -2,147,483,647 to 2,147,483,647 with min no more than max (or else BATUTIL exits with an error). It returns the values 0 if the string is number between min and max (inclusive) 1 if the string is a number greater than max (but no more than 2,147,483,647) 2 if the string is a number less than min (but not less than -2,147,483,647) 3 if it is not a number or not in the range -2,147,483,647...2,147,483,647 VI.4 Date Arithmetic Metastrings: $J(...), $M(...), $D(...), $Y(...), $W(...), $E(...) BATUTIL understands four forms for the date, three for input and three for output (with an overlap of two) - metastring translations freely transform from an input form to an output form. The three formats for input are: - MM-DD-YY or MM/DD/YY apologies to Europeans for using the American convention of MM/DD not DD/MM - the number of days since 12/31/79 with 1/1/80=1 - the date assigned to a file name The three formats for output are: - MM/DD/YY as above - days since 12/31/79 as above - the date and weekday in English, e.g. Sunday, September 15, 1991 Chapter VI:BUSIC Page 86 Documentation for BATUTIL, Version 4.0 The six date connected metastrings $J, $M, $D, $Y, $W, $E correspond to the components of the output types. They take an argument in (...) or if an argument is missing, they use today. The arguments correspond to the three input type. BATUTIL first looks for an integer between 1 and 7305 since the number of days from 12/31/79 to 12/31/99 is 7305. This version of BATUTIL only understand dates in that range (contact us if you'd like to see this restriction removed). It then looks to interpret the argument in the form MM/DD/YY or MM-DD-YY and if that fails, it will use the argument for a filename. YY could be either 91 or 1991. If you make an error like write 9\15\91, you'll get an invalid pathname error since the last thing that BATUTIL will try is to take that string as a filename. The metastrings are the following: $J = number of days since 12/31/79 in the Julian calendar $M = month $D = day $Y = year $W = weekday $E = date in English For example $J(9/15/91) = 4276 $M(4276) = 09 $D(4276) = 15 $Y(4276) = 91 $W(4276) = Sunday $E(4276) = September 15, 1991 The use of conversion from MM/DD/YY and filename to English and weekday should be clear but why care about $J and that form of date? Simple - to do date arithmetic and date comparisons. If you want to know the date 50 days from now use $E($V(50+$J)). If you want to know the number of days between 1/24/81 and 4/16/91 try $V($J(4/16/91) - $J(1/24/81)) If you want to list all files at no more than 5 days old, you'd use: for $1 in (*.*) do if $J($1) > $V($J - 5) then echoln $1 [NOTE: At the DOS command line remember to use $g not >.] Chapter VI:BUSIC Page 87 Documentation for BATUTIL, Version 4.0 VI.5 Reading from and Writing to Files Commands: >, $Rtranslate, $Wtranslate, IOerror Parameters: +/- for $R, $W and IO Metastrings: $R(...), $R(con), $R, $% BATUTIL can read and write to text files. The commands to write to a file are ONLY valid in a INclude set of commands and involve expanding the ECho command. Reading from a file involves the $R command. You can also read from the screen. The first time $R is used after a given time that BATUTIL is loaded, it is REQUIRED that a filename follow the $R in the form $R(filename) There are two variants on this syntax. If the filename is proceeded by a + sign, the file is chosen for reading but the first line is not actually read. If the first letter is a - sign, the file reading is begun again from line 1. If you want to do both, that is return the read pointer to the first line but not actually read a line, then use +-. Each time a $R appears without a (..) after the initial $R(...), the next lines of the file is read. The line number of the last line read is normally stored in the variable $9. You can change the next line read by changing $9 since each $R read reads line number $9 + 1. There are two times that $R returns an empty string. If it has the form $R(+filename) or if the end of the file has already been reached. If a line has more than 255 characters, only the first 255 characters are read in for $R. If a $R read is successful and the last line read is not the end of the file, then the internal variable $% is set to 0. If the end of the file has been reached, then $% is set to 1. Thus, for example $1=$R(+somefile) REPEAT $1=$R UNTIL $%=1 echo the file has $9 lines would count the number of lines in a file. Normally, if there is a file error in attempting to read from a file, BATUTIL exits with an error message but if you want to trap Chapter VI:BUSIC Page 88 Documentation for BATUTIL, Version 4.0 these errors, you can prevent the exit by using the command IOerror - (and you can restore the default behavior with IO +). This prevents exits for file reads and writes via $R and echo only. Once IOerror exits are turned off, the first file error on read is indicated in the variable $% with values: 2: file not found 9: invalid path 230: drive not ready 231: other file error By default, metastring translation is OFF for file reads but you can turn it on with the command $Rtranslate + BATUTIL acts specially if the file indicated for a $R metastring is called CON. In that case the variables $7, $8, $9 are used. $9 must be set and have a value in the range 1 to 255 - it indicates the number of characters to be read. $7 sets the screen row and $8 the column. If they are empty, they are interpreted to be 0. The there is an explicit + or - or the value is 0, the row and/or column are relative to the current cursor position - otherwise they are absolute. For example, the following set of command would read the line before the current one, delete leading and trailing blanks and store the result in the variable $1: #T C $9=$r $7=-1 $8=1 $1=$R(con) $1 = $s(T,$1) Recall that #T C returns the number of columns on the monitor. In an INcluded set of commands, you can write to a file by using ECho and the > sign. That is EC some string> somefile would delete any file of that name and write the file with the string in it (after metastring translation). If >> were used instead of >, then BATUTIL will append just as DOS does. If the filename is replaced by the symbol *, then the last filename used is used again and append is automatically on. If the first symbol after a single > is a ? and the file exists then BATUTIL displays a message: Chapter VI:BUSIC Page 89 Documentation for BATUTIL, Version 4.0 File exists: filename <A>ppend, <O>verwrite, <C>ancel? A CR/LF is automatically added to the end of any line sent to a file with > or >> so the ln in echoln would be ignored in this case. But explicit $_ are translated. While metastring translation is ON for file writes, you can turn them off with $Wtranslate - The valid values for $% on write errors are 9: invalid path 5: file is read only 230: drive not ready 231: other file error VI.6 BUSIC Summary and Overview BUSIC proper has eight commands. Two - GOto and LAbel have minimal truncations - but the other six IF, WHILE, CALL, FOR, REPEAT and CASE do not and must appear in full (although they are case insensitive). In addition the language has several keywords which don't appears as commands (i.e. at the start of a line and causing action) - BEGIN, END, RET, UNTIL, ENDCASE, ELSE - they also must appear in full but are case insensitive. Three of the commands - IF, WHILE, REPEAT concern comparison strings with the same syntax as the HALTIF command of Version 1.0. That is the comparison string first has metastring translation and then the characters >, < or = are scanned for the strings on each side are compared. If both strings can be interpreted as numbers up to 2,147,483,647 in absolute value, the compassion is done that way, otherwise as strings. For numbers, the meaning of < and > is clear. For two strings, S1 and S2, we say S1 < S2 if length(S1) < length(S2) or if the lengths are equal and the strings are equal up to a point where the character in S1 comes before the one in S2 in the ASCII table (that is space is smallest, then number, then caps and then lower case). In this version, AND and OR are not supported. If the first character in the string is ~ then the negative is taken of the string Chapter VI:BUSIC Page 90 Documentation for BATUTIL, Version 4.0 without ~. Because of the metastring translation, you can use $g and $l for > and <; indeed, you must on the DOS command line since > and < will reinterpreted as redirection commands. In brief, the syntax is IF compare THEN thencmd ELSE elsecmd WHILE compare DO command FOR $A= start to stop DO command ($A is one of $0,...,$9) REPEAT several commands UNTIL compare CASE string OF poss1:cmds poss2:cmds .... else: cmds ENDCASE LA labelname GO labelname CALL labelname The DO in WHILE and FOR and the OF in CASE are optional. ELSE is optional in IF. Details are discussed in separate sections below. The thencmd and elsecmd in an IF and the commands in FOR and WHILE can become several commands with BEGIN/END as in FOR $1=1 to 10 BEGIN $2=$v($1**2) $3=$v($1**3) ec The square of $1 is $2 and its cube is $3. END Commands must be on separate lines or separated by [] as usual. BEGIN must be on the same line as IF, FOR or WHILE. The END should be on a line by itself unless followed by an ELSE. Chapter VI:BUSIC Page 91 Documentation for BATUTIL, Version 4.0 REPEAT/UNTIL has an implied BEGIN/END and you should not use an explicit one. Each cmd after a case possibility can be multiple. There is also a BEGIN/END implied. VI.7 LABELS, GOTO and CALL Commands: LAbel, GOto, CALL Keywords: RET paired to LAbel on a CALL BATUTIL program flow is controlled with BATUTIL labels (not to be confused with batch file labels which start with : and are used by the command file reading routines in BATUTIL). The syntax is LAbel labelname where as usual LAbel means that LA is the minimal truncation. Labels are not case sensitive and can include any characters except for [ ] { }. Spaces are allowed in the middle of a label but leading and trailing spaces are removed. Labels may be up to 100 characters although obviously, you'll normally want labels of no more than 10 or 12 characters. Labels over 100 characters will not produce an error and may work but there could be unexpected behavior. Metastring translation does NOT take place when the LA command is evaluated. When LA commands are reached, no action is taken - that is just like batch files, those lines are skipped. When a label is called by a GOto or CALL command, all commands in memory are searched but labels in sections of code that are to be entered with an INclude command are only searched if that INclude command has been acted upon already. Sections of code that are issued via an INclude command which is part of a CALL, REPEAT or BEGIN/END pair are removed from memory when that CALL, REPEAT or BEGIN/END is over. Two sets of labels have special meaning: labels which start with BATUTIL followed by extra characters are used internally by BATUTIL and you should avoid them. The label ELSE has special meaning. During the processing of GOto and CALL commands, if a label is not found, then the label ELSE is searched for and GOto or CALL control is passed there. Labels are searched for in the current loop or BEGIN/END action (in the current command level as discussed in Section 11) and then successively up through nested loops until the main set of commands Chapter VI:BUSIC Page 92 Documentation for BATUTIL, Version 4.0 are searched for. This means if you have an ELSE label as part of a BEGIN/END set of statements as well as an ELSE label which appears earlier in the command list, then upon a label not found error, control will go to the first ELSE when not in the BEGIN/END chain and the second ELSE when in the BEGIN/END chain. Except for this use of ELSE labels, we suggest avoiding duplicate label names. The syntax for a GOto command is GOto labelname Metastring translation is done on this labelname so a command after a menu choice GO menu$r will work the way you'd expect. When a GO command is reached, script flow passes to the command following the corresponding label. There are several special labelnames which cause special behavior in the context of a GOto command: GOto HALT will exit BATUTIL with errorlevel set to 0 GOto HALTxxx will exit with errorlevel xxx where xxx is in the range 0 to 255 GOto EXIT will exit the current CALL, FOR loop, etc technically go down a command level GOto EXITxx will go down xxx command levels where xxx is in the range 1-10 The CALL command is used for subroutines. Its syntax is CALL labelname It searches for a label and also turns control over to the command following the label. But it remembers the location of the CALL. When a RET command is encountered, BATUTIL returns to the command following the CALL. Nested CALLs are allowed limited only by memory (we've found typical nesting limits are 30-40 levels deep which should suffice unless you have a logic flaw). If memory runs out, an error message is issued and BATUTIL exits. BATUTIL actually looks for the matching RET at the time the CALL begins and exits with an error if none is found. If a RET is encountered in the middle of BATUTIL processing except as part of a CALL, then you'll get an Unmatched RET error. For this reason, you'll normally want to place all subroutines at the start or at the end of your code and jump over them. The start mode has the form: GO code Chapter VI:BUSIC Page 93 Documentation for BATUTIL, Version 4.0 LA sub1 ..... {subrountine 1 code} RET LA sub 2 .... {subrountine 2 code} RET .... {other subrountine code} RET LA code .... {main code} while the end mode has the form .... {main code} GO halt LA sub1 ..... {subrountine 1 code} RET LA sub 2 .... {subrountine 2 code} RET .... {other subrountine code} RET As an alternative, you could make libraries of subroutines in files called whatever.sub and have whatever.sub have the form GO endwhatever LA sub1 ..... {subrountine 1 code} RET LA sub 2 .... {subrountine 2 code} RET .... {other subrountine code} LA endwhatever with the main file start with INclude whatever.sub VI.8 IF...THEN...ELSE and CASE Commands: IF, CASE Keywords: THEN, ELSE, BEGIN, END, ENDCASE, OF There are two forms for the IF command without ELSE clause IF compare THEN thencmd or Chapter VI:BUSIC Page 94 Documentation for BATUTIL, Version 4.0 IF compare THEN BEGIN thencmd1 thencmd2 .... END and there are four forms with the ELSE command IF compare THEN thencmd ELSE elsecmd or IF compare THEN BEGIN thencmd1 thencmd2 .... END ELSE elsecmd or IF compare THEN thencmd ELSE BEGIN elsecmd1 elsecmd2 .... END or IF compare THEN BEGIN thencmd1 thencmd2 .... END ELSE BEGIN elsecmd1 elsecmd2 .... END Put briefly, the else clause is optional and the basic IF compare THEN thencmd ELSE elsecmd can have either thencmd and/or elsecmd replaced by a set of commands flanked by a BEGIN/END pair. As usual, the commands and keywords need not be capitalized. However, they may not be truncated. Moreover, the syntax of separate lines (or separations with {}[]) must be observed. As you'd expect, if the comparison in "compare" is true, then thencmd(s) are issued. If it is false, the elsecmd(s) are. Nested IF...THEN's are allowed but be careful of the following ambiguous situation: Chapter VI:BUSIC Page 95 Documentation for BATUTIL, Version 4.0 IF compare1 THEN IF compare2 THEN cmd1 ELSE cmd2 Resolve the ambiguity by using either IF compare1 THEN BEGIN IF compare2 THEN cmd1 ELSE cmd2 END or IF compare1 THEN BEGIN IF compare2 THEN cmd1 END ELSE cmd2 CASE commands have the syntax CASE string OF choice1: cmd11 cmd12 choice2: cmd22 ..... ENDCASE The keyword ENDCASE is required. If it ever occurs except as a match to a CASE, there will be an exit with error. The OF is optional. The string has metastring translation done but the choices do not. There is an implied BEGIN/END after each : - do not use an explicit one. If you ever need a command with a : in it, and it is not on the same line as the choice:, then enclose it in double quotes. Explicitly nested CASE statements are NOT allowed but you can CALL a subroutine with a CASE statement from within another CASE statement and so get the same effect. VI.9 FOR, REPEAT and WHILE Commands: FOR, REPEAT, WHILE Keywords: =, UNTIL, TO, DO In this section, we discuss three loop commands which allow repetition with one of more variables changed. Note that the FOR loop has an explicit variable changed while you'll need to change something in a WHILE or REPEAT loop to avoid looping indefinitely (remember ^-Break to get out if need be). Chapter VI:BUSIC Page 96 Documentation for BATUTIL, Version 4.0 The FOR command has two forms - a list, as discussed in the next section and a numeric form. The numeric form has two versions: FOR $*= start TO stop DO cmd or FOR $*= start TO stop DO BEGIN cmd1 cmd2 .... END $* must be one of the thirty variables $1,...,$0,$é,...,$ò. TO is a required keyword and DO is optional. "start" and "stop" must both be integers in the range -32767,...,32767. $* is increased/decreased one at a time depending on whether stop is larger/smaller than start. If start=stop, then the command is done once. Metastring translation is done to both start and stop. Nested FOR loops are allowed but be careful to use different variables. In general, be careful to avoid accidentally changing a for variable in the commands issued during the FOR loop. WHILE loops have the form either WHILE compare DO cmd or WHILE compare DO BEGIN cmd1 cmd2 ... END The DO is NOT optional in this case. If compare starts out false, then the loop is not done at all. At the end of each loop, compare is reevaluated and the WHILE terminated if it is false. Be careful to be sure that the loop will produce the changes need to terminate the loop. REPEAT loops have the form REPEAT cmd1 cmd2 .... UNTIL compare Chapter VI:BUSIC Page 97 Documentation for BATUTIL, Version 4.0 REPEAT loops differ from WHILE loops in two ways: - the compare is checked at the end so the loop is always gone through at least once - WHILE loops iterate when compare is true; REPEAT loops iterate when compare is false VI.10 FOR Loops with Lists, Files and Directories Commands: FOR and FORDIR Keywords: IN BATUTIL has loops which will repeat a process with replacement of a variable from an explicit list or one generated by the system. Two of the possibilities are essentially like DOS batch file's for..in...do loops and there is a third for directories. The syntax for the first two is either FOR $* IN (list) DO cmd or FOR $* IN (list) DO BEGIN cmd1 cmd2 .... END As with numeric FOR loops, $* must be one of the thirty variables $1,...,$0,$é,...,$ò and DO is optional while IN is required. The component "list" is a set of words separated by spaces. Metastring translation is not done on the string but is done on each word in the list so that FOR $1 IN (abc$Sdef ghi) DO ECHOLN $1 would output abc def ghi The loop variable which we'll denote $* is set successively to the words on the list so long as those words do not contain the wildcards * or ?. If these wildcards occur in some words, then for those words BATUTIL looks for matching filenames and files those in. There is a limit of roughly 500 total matches on the list. Using FORDIR is similar to using a for loop with filename wildcards but instead it traverses whole directory trees or whole branches. Chapter VI:BUSIC Page 98 Documentation for BATUTIL, Version 4.0 The syntax is FORDIR $* IN (dirlist) DO cmd or FORDIR $* IN (dirlist) DO BEGIN cmd1 cmd2 .... END Dirlist consist of one or more words, each of which is a directory name. $* will then be set successively to each subdirectory of the directories in the list. If dirlist is empty, then a \ is used (i.e. the root is taken so the list of values will be all directories in the list). In each listing, BATUTIL first goes through all directories at a given level, that is for (\), first $* is set to \, then successively all direct subdirectories, than all subsubdirectories, etc. FORDIR is useful for going successively through each directory and issuing commands. With the string manipulation, you could specify a subset of directories with a condition based on the name. In the native output of a FORDIR list, the root directory ends in \ and others do not so if you try something like $1\*.*, it won't be right in the root while, $1*.* won't be right in other directories. The solution is to use $A since $2=$A($1\) would always yield a single trailing backslash. V.11 Internal Structure Most users will be able to skip this section but if you get heavily into BUSIC programming and in particular if you want to use any debugging beyond the simple interactive trace mode, you'll need to know a little about the internal structure of how BATUTIL processes commands. BATUTIL organizes commands into 'levels'. Basically, whenever it needs to process some kind of loop or other nestable structure, it makes a new level and closes that level when the loop, CALL or BEGIN/END sequence is done. A pointer to next command at a given Chapter VI:BUSIC Page 99 Documentation for BATUTIL, Version 4.0 level is kept so BATUTIL knows where to continue when a loop or CALL is done. Each level can accommodate 1024 commands at most and has a minimal overhead of about 4K of RAM plus the total lengths of all the commands actually present at that level. BATUTIL begins by reading in all commands in the BU@ environmental variable and parses that into separate commands which it places into command level zero. It then looks at its command line, parses it and places those commands after the BU@ commands. Whenever it places a command into a level, it checks the first command word to confirm that it is a legitimate BATUTIL command. It will truncate commands with a minimal truncation to two letters but otherwise does no syntax checking or command translation at that time. It then begins analyzing and carrying out the commands at cmdlevel 1. If it comes across an INclude (equivalently FCommand) command, it reads in the commands from the file inserting them into the set of commands it keeps in memory. A new level is not made for such an INclude. The two primitive BUSIC commands are GOto and the non-compound IF..THEN..ELSE. GOto is processed by looking for LAbels - first from the start of the current command level and then successively down one level at a time. When the label is found, all higher levels are disposed of and processing is begun at that label. A CALL is processed by copying all the commands from the label to the next RET into a new cmdlevel and starting that command level. The simplest situation requiring a new level is a BEGIN/END pair. When an IF..THEN..ELSE condition determines that a set of commands in between a BEGIN/END needs to be processed, BATUTIL, copies those commands to a new level and starts with the first. Most other BUSIC commands are translated internally into the two basic primitives. Explicitly: FOR $1=1 TO 17 DO BEGIN cmd1 cmd2 END has BATUTIL SEt $1 to the value 1 and produces a new cmdlevel with Chapter VI:BUSIC Page 100 Documentation for BATUTIL, Version 4.0 commands of the form: LA BATUTILxxx (where xxx is a number) cmd1 cmd2 ++$1 IF ~$1=17 GOto BATUTILxxx WHILEs and REPEATs are translated into similar by hand loops. FOR lists and FORDIR have BATUTIL first evaluate the list if it has files (or directories). Then if the DO is a single command, a crude set/cmd succession is done. If a set of commands, then a CALL is used instead. Thus FOR $1 in (abc def ghi) do cmd1 would produce a cmdlevel SEt $1=abc cmd1 SEt $1=def cmd1 SEt $1=ghi cmd1 while FOR $1 in (abc def ghi) do begin {} cmd1 {} cmd2 {} end would produce a cmdlevel LA BATUTILxxx cmd1 cmd2 RET SEt $1=abc CALL BATUTILxxx SEt $1=def CALL BATUTILxxx SEt $1=ghi CALL BATUTILxxx where the pointer to the starting command is placed right after the ret when the level begins. CASE statements make use of gotos with a variable label. So, for example CASE $1 OF abc: cmd11 cmd12 def: cmd21 cmd22 ENDCASE Chapter VI:BUSIC Page 101 Documentation for BATUTIL, Version 4.0 would produce a new cmdlevel of the form: CALL BATUTILxxxN$1 ~ GO exit LA BATUTILxxxNabc ~ cmd11 cmd12 RET LA BATUTILxxxNdef ~ cmd21 cmd22 RET VI.12 Trace Mode Command: TRace Parameters: Ffilename, Wvarname, W-, ON, OFF, *, %, nnn, $nn, Xnn, X$nn BATUTIL comes with a debug mode. The simplest version of it and the one most users will restrict themselves to is interactive trace mode. This is turned on with the command {TRace on} or if you hit ^-Break, and answer NO to the first question about halting BATUTIL, you get a chance to turn trace on. Trace will be turned on AFTER the current command is executed. Once on, you can turn trace off with an explicit {TRace off} in the code stream or with one of the interactive commands. When in trace mode, a little menu appears at the top of the screen: BATUTIL's Interactive Trace Facility Next command is EC hi (C)ontinue, (H)alt, (E)nvironmental variables, (I)nternal variables (L)ook at screen, (T)race off, (P)ause off Here is what each choice means: C (or <Enter> or <Esc>) : execute next command H : end this running of BATUTIL E : call up the interactive environment viewer/editor (same as batutil {ED}) Chapter VI:BUSIC Page 102 Documentation for BATUTIL, Version 4.0 I : call up the interactive internal variable viewer/editor (same as batutil {ED $}) L : display 5 lines at the top covered by the menu; return to menu with any key T : turn off master debug switch (same as {TRace off}) P : turns off pause after each command but will continue writing to file or screen (same as {TRace X32}; see below) After, E, I or L, the menu will reappear before the next command is issued. Any editing you do of the environment or internal variables which you save will be in effect for subsequent commands. In addition to this interactive mode, BATUTIL can send information to a file (or screen) - often a very large amount of information. For example with % debug info turned on (see below), the simple set of BATUTIL commands FOR $1=1 TO 10 BEGIN CO 15 FOR $2=1 TO 10 ECho $s(F,$V($1*$2),R,4) ECHOLN END produces a debug file which is almost half a megabyte! BATUTIL keeps the track of what kind of debug information you want with a byte - a number from 0 to 255 which is a sum of some subset of the following values: 1 = master switch 2 = whether debug info is sent to screen 4 = whether all non blank internal variables are reported 8 = whether to report on variables explicitly watched 16 = whether to report on environmental variables 32 = whether to interactively debug 64 = whether to show the current level of commands 128 = whether to show all commands Obvious overrides hold - for example, if 128 is on, then 64 is ignored. The master switch by itself does nothing but it must be on to have any debug actions taken but without any other switches on all is save to the debug file is the next command. The purpose of the master switch is to have {TR X1} toggle on/off debug keeping all the other debug options in place. Chapter VI:BUSIC Page 103 Documentation for BATUTIL, Version 4.0 Modes are controlled with parameters to the TRace command. Here are the allowed parameters: F followed by a filename with or without path; no spaces after f W followed by an environmental variable turns on watch for that variable W- followed by an environmental variable drops watch for that variable nnn for a number is the same as turning on the flags above for example if nnn=161, the 1, 32 and 128 switches would be turned on $nn like nnn but nn is now a Hexadecimal number Xnnn xors the flags with nnn X$nn xors the flags with nn hex OFF turns off the master switch; leaves the other flags alone ON is the same as 33 (turns on master switch and interactive mode) % same as 133 - master, plus all commands plus internal variables - best for reporting to a file * same as 181 - master switch, all commands, all environmental and internal variables plus interactive Here are a few details of some of the parameters. The filename that appears after F with no spaces (e.g. {TR FC:\trace.txt %}) will be erased if it already exists without warning - the assumption is that you'll reuse the same file over and over. If there is a problem with the file (invalid path at startup, disk full....), BATUTIL will report to you: Fatal error with debug file <filename> Error involves <error type> No longer writing to file; writing to console instead. Hit a key to continue. (<Esc> aborts.) Esc will abort; any other key will continue with debug information written to the screen. BATUTIL keeps a list of up to 64 variables which it will explicitly track in reports. You add/delete from this list with the W and W- commands. Either environmental or internal variables can be watched. You have watched variables added to the debug file by turning on the switch with value 8. If you prefer you can have all environmental and/or all internal variables reported with the 4 and Chapter VI:BUSIC Page 104 Documentation for BATUTIL, Version 4.0 16 switches. VI.13 Hacker Mode Command: HACKER + Metastrings: $Z(XXXX:YYYY), $z(YYYY) BATUTIL has the equivalent of BASIC's PEEKs, POKEs, INs and OUTs. Since the commands that write to memory and ports can cause havoc in careless hands, BATUTIL is set up to not allow these commands. You must explicitly turn on "hacker mode" to enable the metastrings below - if you do not, you'll get metastring translation errors if you try to use these strings. You turn on hacker mode with {HACKER +} the word must be spelled out in full. Once hacker mode is one you can: Read from memory: anywhere that metastring translation is on $Z(XXXX:YYYY) will read the byte in memory at address XXXX:YYYY (hex) and replace that string with the corresponding Hex value. For example IF $Z(0:417)=40 THEN ECho Capslock is on Write to memory: If Hacker mode is on SEt $Z(XXXX:YYYY)=GG will write the hex value GG to address XXXX:YYYY. For example SEt $Z(0:417)=40 will turn on capslock. Read from a port: anywhere that metastring translation is on $z(XXXX) will read from that port and replace that string with the corresponding Hex value. XXXX is in Hex. Write to a port: If Hacker mode is on SEt $z(XXXX)=GG will write the hex value GG to port XXXX. Chapter VI:BUSIC Page 105 Chapter VII:TIPS AND EXAMPLES VII.1 General tips After a BATUTIL menu, you'll typically need to branch on a number of different possibilities. The commands IF $r=6 GOto menu6 IF $r=5 GOto menu5 IF $r=4 GOto menu4 IF $r=3 GOto menu3 IF $r=2 GOto menu2 IF $r=1 GOto menu1 followed by choice 0 code will work but the following is more elegant. If there are six menu choices, have labels menu0,..., menu6. Use GOto menu$r For an example of this see the sample batch file BUDEMO.BAT. It is most convenient to place the fmenu and fecho lines in the batch file itself. If the batch file is foobar.bat, you could use {FEcho foobar.bat label} but that will fail if the user renames the batch file so use {FEcho %0 label} instead. To handle this possibility, BATUTIL looks first for the filename specified with a {fecho ....} command by name and if that fails it tries the extension bat. VII.2 Returning to your Initial Directory You can arrange to return to your initial directory in a batch file, say one that changes to C:\123 and runs lotus with batutil {SEt dr=$n di=$p} C: cd \123 lotus %dr%: cd %di% This uses DOS' environmental substitution. You could arrange to save a set of your earlier directories and return to them with two batch files, pushdir and popdir. Pushdir.bat would read batutil {SEt dr3=$x(dr2) di3=$x(di2) dr2=$x(dr1) di2=$x(di1) dr1=$n di1=$p} all on one line. Popdir would read Chapter VII:TIPS AND EXAMPLES Page 106 Documentation for BATUTIL, Version 4.0 %dr1% cd %dr1% batutil {SEt dr2=$x(dr3) di2=$x(di3) dr1=$x(dr2) di1=$x(di2) dr3= di3= } In terms of directory manipulation, suppose you not only want to return to the original directory but you have a program silly in \foo which insists that its directory be in the path even if it is the default directory. You want to add it to the path but later remove it. Use: batutil {SEt dr=$n di=$p}{ad C:\foo} C: cd \foo silly batutil {DE C:\foo) %dr%: cd %di% VII.3 Using BATUTIL in your autoexec.bat There are a number of actions special to an autoexec.bat that make BATUTIL valuable. Your autoexec.bat may take a long time to run because you run a defragmenting utility or use a FAT/root dir saver like DOS' mirror or you might copy a lot of files to a RAM disk. You might care to branch at the end of the batch file, say to run Software Carousel or not. Of course, you can ask a question but what if you don't want to always stand around and would like to default to running Carousel if you aren't there? You could use (as a fragment of your autoexec.bat): batutil {EC Run Carousel (Y/N)?}{GE wa6 y n} if errorlevel 2 goto nocar carousel :nocar You could even have the time counted down by replacing the first line with batutil {EC Run Carousel (Y/N)? $L secs left}{GE wa6 y n} So you've solved the problem of waiting around if you do want to run Carousel. But what if you don't want to? With the above fragment you'd need to wait around. Here is where the test of the lock keys comes in. Immediately before the first line of the above fragment, you could put batutil {QL C-} if errorlevel 1 goto nocar Chapter VII:TIPS AND EXAMPLES Page 107 Documentation for BATUTIL, Version 4.0 Then, if you hit Capslock before you go off Carousel wouldn't run. Actually, you could avoid an extra running of BATUTIL and two lines of the file by using: batutil {QL C-}{IF $r=1 THEN GOto halt2} {EC Run Carousel (Y/N)?}{GE wa6 y n} as the first line of the fragment. For then if Caps was set, the GOto halt2 command causes BATUTIL to exit with an errorlevel of 2 just as if you answered no! Another problem that you'll often want to cope with in a batch file is some operation, like defragmentation that you only want to run once a day. Here is a fragment to do that: batutil {TO newday.tst} if not errorlevel 1 goto already echo a >newday.tst STUFF TO DO ONCE :already What this does, is if the error level is exactly 0, then one skips to the label already. Otherwise, the file newday.tst is given today's date so that the next time it is run, "batutil {to newday.tst}" will return errorlevel 0. But what if you sometimes work past midnight and don't want the newday stuff done until morning? Replace batutil {TO newday.tst} with batutil {TO 5 newday.tst} which will make the change over at 5AM rather than midnight. VII.4 A Clean Sweep Here is a simple BATUTIL code fragment that will delete all *.bak files anywhere on disk. SEt buswap=! FORDIR $1 IN () DO BEGIN $2=$A($1\) NU $!($2*.bak) IF $r > 0 THEN BEGIN RUn command /cdel $2*.bak ECho $1:$r files erased END END Chapter VII:TIPS AND EXAMPLES Page 108 Documentation for BATUTIL, Version 4.0 Note the use of $2=$A($1\) to place a single trailing backslash as explained in Section VI.10. Note the supermetastring $! in the nu command, necessary because metastring translation is not done on that command. VII.5 Directory Lister with Smart Wildcards PC Magazine's user to user column has had a number of letters about how to get a name listing of all files whose names includes a string anywhere in the filename, see, for example v10, n16, pg 424. Here's a way to do it with BUSIC: @echo off if '%1'=='' goto error batutil {$1=%1}{IN %0 code} for %%a in (%foo##%) do echo %%a set foo##= goto end :code $2=$s(S,$1) $5=$1*.* $4=? FOR $3=8 TO 2 DO BEGIN IF $2=$3 THEN GO next $5=$5$S$4$1*.* $4=?$4 END LA next CASE $2 OF 1: $5=$5$S*.$1*$S*.?$1*$S*.??$1 2: $5=$5$S*.$1*$S*.?$1 3: $5=$5$S*.$1 ENDCASE SET foo##=$5 :error echo a parameter is required :end VII.6 A Two Year Olds' Delight Here is a simple batch file which delighted Barry's two year old daughter for %%a in (1 2 3 4 5 6 7 8 9) do batutil {GE IN}{SO 1%%a} This will wait for the insert key and then play 9 tunes. The INsert key was especially picked for two reasons: it is large and Chapter VII:TIPS AND EXAMPLES Page 109 Documentation for BATUTIL, Version 4.0 easy for little hands to reach. It is not a repeating key so that it is less likely that several keystrokes will get through and abort the tunes. VII.7 Sample Batch Files You will learn a lot about how to use BATUTIL by studying the sample batch files provided. We'll make some comments about them here. The complicated contortions in the BATUTIL 1.0 manual are no longer needed because we can use internal variables on the whole. Notice that we use {RC $} command to prevent RC from being placed in the environment. Budemo {FEcho %0} and a variant on the goto fmenu$r tricks discussed in Section 1 (we use CALL in place of GOto). It turns the cursor off with the set cur=off command. Most of the separate batch demos are called with a simple use of FCommand. Notice that this use allows the same code to be used to call the subsidiary batch files from within BUDEMO.BAT as well as stand alone. Notice how BUDEMO sees if batutil.hlp is in the current directory or on the path and stores the information in $Å. It then calls the appropriate menu with a FM $!(%0 fmain$Å) The supermetastring $!(...) is needed because FM does not normally do metastring translation. Because calling help requires a separate running of BATUTIL, we need some fancy footwork with DOS batch files to call help from the ninth menu choice. Soundemo.bat is also straightforward. Note the way the fpretty command is used to produce the second screen with its special box. Showdemo's most interesting feature may be the last panel that illustrates how to use the fpretty command for a display of Chapter VII:TIPS AND EXAMPLES Page 110 Documentation for BATUTIL, Version 4.0 different columns in different colors. Note the use of the $$. Note inputdem's use of $L with spaces after it. Note that equip gets all its information and saves it in internal variables and then displays it all at once. The study of these samples should give you an idea of how to use BATUTIL. Chapter VII:TIPS AND EXAMPLES Page 111 Chapter VIII:COMMAND REFERENCE In this chapter, we present an alphabetical list of commands with a complete reference for each command in the following format: COMMAND []/{} Input: INPUT Output: OUTPUT Parameters: LIST DESCRIPTION Values: LIST Manual reference: LIST Examples: SAMPLES Internal parameters: LIST See also: LIST ---------------------------------------------------------------------- Hereafter each command appears []/{} or just {} to indicate whether the command can appear on the command line only within {} or if [] is also allowed. The items in CAPS change from item to item. Input is one or more of the following (inside [] we indicate the abbreviation used): Cmdline [CM] indicates the command takes parameters System [SY] indicates that it reads the internals of your computer Batutil [BU] uses internal flags in BATUTIL User [US] input from user required File [FI] text in a file between sets of labels Output is one or more of the following (inside [] we indicate the abbreviation used): Errorlevel [EL] sets errorlevel and/or the variable RC Environment [EN] effects one or more environmental variables Display [DI] displays on screen or speaker Internal [IN] if an internal flag like CS is effected External [EX] some other program or file is effected If a command is a BUSIC Command or Keyword, we say so instead of listing Input and Output Fields Values only appears if the commands returns one of a set of numbers and lists those values. Internal parameters lists the internal flags (if any) like CS which BATUTIL keeps and which effect the command. Manual reference gives cross references to the manual. ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 112 Documentation for BATUTIL, Version 4.0 #Altmon []/{} Input: SY Output: EL Parameters: None Returns the type of a second monitor, if any Values: 0 = none 8 = vga color 1 = monochrome (MDA) 11 = mcga mono 2 = cga color 12 = mcga color 4 = ega color 21 = hercules mono 5 = ega mono 22 = hercules monochrome plus 6 = prof. graphics 23 = hercules Incolor 7 = vga mono Manual reference: Section II.4 Examples: batutil [#A] See also: #Terminal, #Whichmon, @Terminal ---------------------------------------------------------------------- #Comm []/{} Input: SY Output: EL Parameters: None Returns the number of comm ports from 0 to 4 as determined from non-zero addresses in the BIOS area. If there are more than two comm ports, this number may not be accurate since DOS only supports two comm ports and some non-standard method may be used by the system. Values: 0 through 4 Manual reference: Section II.5 Examples: batutil [#C] ---------------------------------------------------------------------- #Disk []/{} Input: SY Output: EL Parameters: Drive letter; no parameter means default drive This command returns the total disk space; for drives A and B in units of 8K; for other drives in units of 256K; rounded down; capped at 199. Values: 0 to 199; 239 means invalid drive letter or drive not ready Manual reference: Section II.3 Examples: batutil [#D C] See also: @Disk ---------------------------------------------------------------------- #Env []/{} Input: SY Output: EL Parameters: None Total environment space in units of 16 bytes up to 3184. Values: 0 to 199 (199 for 3184 bytes of environment or more) Manual reference: Section II.3 Examples: batutil [#E] See also: @Env ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 113 Documentation for BATUTIL, Version 4.0 #Floppy []/{} Input: SY Output: EL Parameters: None Number of floppy drives as reported by the BIOS equipment byte Values: 0 to 4 Manual reference: Section II.5 Examples: batutil [#F] See also: @Floppy ---------------------------------------------------------------------- #Game []/{} Input: SY Output: EL Parameters: None Number of game ports as reported by the BIOS equipment byte Values: 0 or 1 Manual reference: Section II.5 Examples: batutil [#G] ---------------------------------------------------------------------- #Intel []/{} Input: SY Output: EL Parameters: None Returns the CPU type Values: 0 = 8086/8088; 1 = 80186; 2 = 80286; 3 = 80386; 4 = 80486; 20 = NEC V20/V30 Manual reference: Section II.5 Examples: batutil [#I] See also: @Intel ---------------------------------------------------------------------- #Keyboard []/{} Input: SY Output: EL Parameters: None Tests for the presence of BIOS support for the enhanced (101 key) keyboard Values: 0 = not enhanced; 1 = enhanced Manual reference: Section II.4 Examples: batutil [#K] ---------------------------------------------------------------------- #Lim []/{} Input: SY Output: EL Parameters: None Reports the total amount of Lotus Intel Microsoft Expanded memory in units of 64K up to 12736 K (rounded down) Values: 0 to 199 (0 if no EMS) Manual reference: Section II.3 Examples: batutil [#L] See also: LIm, #Mem, #Xtended, @Lim, @Mem, @Xtended ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 114 Documentation for BATUTIL, Version 4.0 #Mem []/{} Input: SY Output: EL Parameters: None Returns the total DOS memory in units of 4K rounded down (640K corresponds to 160; because PS/2's have only 639K, 159 will be reported) Values: 0 to 160 Manual reference: Section II.3 Examples: batutil [#M] See also: #Lim, #Xtended, @Lim, @Mem, @Xtended ---------------------------------------------------------------------- #Prn []/{} Input: SY Output: EL Parameters: None Returns the number of printer ports (to which printers may or may not be attached) Values: 0 to 3 Manual reference: Section II.5 Examples: batutil [#P] See also: @Prn ---------------------------------------------------------------------- #Rodent []/{} Input: SY Output: EL Parameters: None Returns 0 if no mouse; 1 if a mouse is present Values: 0 or 1 Manual reference: Section II.4 Examples: batutil [#R] ---------------------------------------------------------------------- #Terminal []/{} Input: SY Output: EL Parameters: None, R, S or C Returns 1 or 2 depending on the number of monitors if no parameter; number of Rows, Columns or Special=Rows - 1 Values: 1 or 2; R=25,43,50 typically; C=40 or 80 typically Manual reference: Section II.4 Examples: batutil [#T]; batutil {#T R}{EC Screen has $x(rc) rows} See also: @Terminal, #Altmon, #Whichmon ---------------------------------------------------------------------- #Vmode []/{} Input: SY Output: EL Parameters: None Returns the currently active mode, e.g. 7 for monochrome text, 2 or 3 for text on a graphics monitor, 16 for EGA hires graphics, etc. Values: 1 to 16 Manual reference: Section II.4 Examples: batutil [#V] See also: #Terminal, #Altmon, #Whichmon, @Terminal ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 115 Documentation for BATUTIL, Version 4.0 #Whichmon []/{} Input: SY Output: EL Parameters: None Returns the type of the currently active monitor Values: 8 = vga color 1 = monochrome (MDA) 11 = mcga mono 2 = cga color 12 = mcga color 4 = ega color 21 = hercules mono 5 = ega mono 22 = hercules monochrome plus 6 = prof. graphics 23 = hercules Incolor 7 = vga mono Manual reference: Section II.4 Examples: batutil [#W] See also: #Terminal, #Altmon, #Vmode, @Terminal ---------------------------------------------------------------------- #Xtended []/{} Input: SY Output: EL Parameters: None Amount of AT extended memory in units of 64K rounded down up to a maximum of 12736K; with more than that 199 is returned. On an 80386 machine with 386 control software, this number may not be reliable. Values: 0 to 199 Manual reference: Section II.3 Examples: batutil [#X] See also: #Lim, #Mem, @Lim, @Mem, @Xtended ---------------------------------------------------------------------- $!(...) Input:CM Output: IN For ANY BATUTIL command, if the command is given in the form command $!(...) then ... undergoes metastring translation and is passed to the command. This allows you to force metastring translation of parameters for commands that do not normally get such translation. Manual reference: Section I.5 ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 116 Documentation for BATUTIL, Version 4.0 $% Input: BU Output: EN, DI When IOError is turned off, errors during file read/write (via $R and >) do not cause fatal errors but instead set the value of $% which can be accessed in an IF statement, echo or set. Possible values are 0: no error, additional lines in the file 1: no error but at end of file 2: file not found 9: invalid path 230: drive not ready 231: other file error Manual reference: Section VI.5 Examples: IO - [] $R(foobar.txt) [] if $% > 0 then goto fileerror See also: IOerror, $R ---------------------------------------------------------------------- $1,...,$0,$é,...,$ò in diverse cmd Input: BU, US Output: IN BATUTIL keeps 30 internal user set variables. Manual reference: Sections VI.1, V.4 Examples: batutil {fordir $2 in () do ++ $1}{EC $1 directories} See also: $1=, SEt, ECho, ++, -- ---------------------------------------------------------------------- $1=,...,$0=,$é=,...,$ò= {} Input: CM Output: IN These commands have an implicit SEt in front so that $1=67 is the same as set $1=67 Manual reference: Sections V.4, VI.1 Examples: batutil {$1=0}{fordir $2 in () ++ $1}{EC $1} See also: $1, SEt, ++, -- ---------------------------------------------------------------------- $A,$a,$B,$C in diverse cmd Input: SY, CM Output: EN,DI Parameters: Filespec in () Parses the file spec in (); $a gives path; $A path with trailing backspace; $B the filename and $C the extension. Manual reference: Section III.2 Examples: batutil {SE file=$f(*.bat) ext=$C($x(file))} See also: SEt, $F ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 117 Documentation for BATUTIL, Version 4.0 $F or $f in SEt command Input: SY, CM, US Output: EN Parameters: None or filespec in () Calls up a file list from which the user can pick a file which then replaces $f in the SEt command Values: 0 = file picked; 1 = unique matching file; 2 = Exit with <Esc>; 3 = Invalid path 4 = No wildcards - file not found; 9 = Invalid path Manual reference: Section V.6 Examples: batutil {EC Pick a batch file}{SE file=$f(*.bat)} Internal parameters: FDIR, NMouse See also: SEt, FDir, $A,a,B,C ---------------------------------------------------------------------- $J,$M,$D, $Y, $W, $E in diverse cmds Input: CM, SY Output: EN,DI Parameters: (...) where ... is one of MM/DD/YY, days since 12/31/79 or a filename Can be used to access a file date or to interchange between two basic formats: MM/DD/YY, days since 12/31/79 which is needed for date arithmetic Manual reference: Section VI.4 Examples: batutil {EC 15 days from now is $E($V($J+15))} ---------------------------------------------------------------------- $L in Echo command Input: CM, SY Output: IN Parameters: None The place where $L would have appeared is remembered by BATUTIL and a subsequent GEtkey with a WAit will have a ticking clock placed in the place. You must place explicit spaces in the echoed string Manual reference: Section IV.5 Examples: batutil {EC Today is $E and you have $L seconds left}{GE WA60} Internal parameters: TimeRow, TimeCol See also: ROw, COl, ATtribute ---------------------------------------------------------------------- $N in SEt command Input: US, BU Output: EN Parameters: None In the midst of a SEt string, $N pauses to get a numeric input from the user and that string then replaces the $N. You set colors with the AT/MN commands. The user must type in a valid number in the range Manual reference: Section V.5 Examples: EC Pick two numbers?$_ ][ SE n1=$N n2=$N EC $_Their sum is Internal parameters: ?Length, ?Size See also: SEt, ?Length, ?Size, QUery, AT, MN, $Q or $? Chapter VIII:COMMAND REFERENCE Page 118 Documentation for BATUTIL, Version 4.0 ---------------------------------------------------------------------- $Q or $? in SEt command Input: US, BU Output: EN Parameters: None In the midst of a SEt string, $Q, and $? pause to get a string input from the user and that string then replaces the $*. $Q uses a standard (===>) prompt and standard colors. $? allows you to set colors with the AT/MN commands and puts no special prompt in. Manual reference: Section V.5 Examples: batutil {EC What is your name?$_}{SE name=$Q} Internal parameters: ?Length, ?Size See also: ?Length, ?Size, QUery, AT, MN, $N, $¿ ---------------------------------------------------------------------- $R and $R(...) in diverse commands Input: FI, CM Output: EN, DI Parameters: filename The first reference to $R must include a filename to use; subsequent $R's will read successive lines from the file storing the current line number if $9. $% is set to 1 if the end of the file has been reached. To restart reading from the current file, just include a minus sign in front of the filename; to choose the file but not read a line, place a plus sign in front. Manual reference: Section VI.5 Examples: IO - [] $R(foobar.txt) [] if $% > 0 then goto fileerror See also: IOerror, $%, $R(con) ---------------------------------------------------------------------- $R(con) in diverse commands Input: SY Output: EN, DI Parameters: none This is just like $R but if the file read from is "con" then the screen is read instead. $9 is the number of characters to be read and must be set to a number from 1 to 255. $7 is the row number and $8 the column number. If the number has a + or - in front or is 0 (the default), the row/column is relative to the current cursor position. Otherwise, they are absolute. Subsequent calls to $R treat it as if con were the file name until it is changed with a $R(...). Manual reference: Section VI.5 Examples: #T C [] $9=$r [] $7=-1 [] $8=1 [] $1=$R(con) See also: IOerror, $%, $R(...) ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 119 Documentation for BATUTIL, Version 4.0 $Rtranslate {} Input: CM Output: IN Parameters: + or - By default, when files are read in with the $R metastring, metastring translation does not take place. You can turn such translation on with {$R +} and can turn it off again with {$R -}. Manual reference: Section VI.5 Examples: batutil {$R+}{$1=$R(foobar.txt)} See also: $R, $R(...), $Wtranslate ---------------------------------------------------------------------- $s in diverse cmds Input: CM Output: EN, DI Parameters: (subcmd,string,extra params) Subcommand Purpose Additional parameter(s) U Uppercase NONE L Lowercase NONE S Size NONE P Position substring C Copy start, length D Delete start, length I Insert substring, position W Word word number (0=total) T Trim NONE F Format L,R,C + length # count character Manual reference: Section VI.2 Examples: batutil {$1=$Q}{$1=$s(W,$1,0)}{EC $1 words} See also: ECho, SEt ---------------------------------------------------------------------- $V in diverse cmds Input: CM Output: EN, DI Parameters: arithmetic string in () This will eValuate a numeric expression using +, -, *, /, \ and ** where ** is power, / is integer division and \ is the mod function. Nested parenthesis are understood. Manual reference: Section VI.3 Examples: batutil {FOR $1=1 TO 10 FOR $2=1 TO 10 echoln $V($1*$2)} See also: ECho, SEt ---------------------------------------------------------------------- $Wtranslate {} Input: CM Output: IN Parameters: + or - By default, when files are written to with the $W metastring, metastring translation takes place. You can turn such translation off with {$W +} and can turn it back on again with {$W -}. Manual reference: Section VI.5 Examples: $W - [] ec $E >> foobar.txt See also: >, >>, $Rtranslate Chapter VIII:COMMAND REFERENCE Page 120 Documentation for BATUTIL, Version 4.0 ---------------------------------------------------------------------- $X or $x in diverse cmds Input: EN Output: EN, DI Parameters: Variable name in () $x(varname) searches the environment for a variable varname and if it finds it replaces $x(varname) by it value. Otherwise $x(varname) is replaced by the empty string. $X translates the value of the variable using metastring translation. Applies to ECho, PRetty, MEnu, SEt commands. Manual reference: Section III.2 Examples: batutil {EC your PATH is $x(path)} Internal parameters: $Translate See also: ECho, FEcho, PRetty, FPretty, MEnu, FMenu, SEt ---------------------------------------------------------------------- $Z in diverse cmds Input: CM Output: EX, DI, EN Parameters: (XXXX:YYYY) where XXXX:YYYY is a hex memory address This metastring only works if hacker mode is turned on. The command SEt $Z(XXXX:YYYY)=WW will write that hex value to memory and ECho $Z(XXXX:YYYY) will read that memory address and echo it to the screen (in hex). Manual reference: Section VI.13 Examples: batutil {SEt $Z(XXXX:YYYY)=WW} Internal parameters: HACKER See also: HACKER, $z ---------------------------------------------------------------------- $z in diverse cmds Input: CM Output: EX, DI, EN Parameters: YYYY where YYYY is a hex port number This metastring only works if hacker mode is turned on. The command SEt $z(YYYY)=WW will write that hex value to the port and ECho $z(YYYY) will read that port and echo it to the screen (in hex). Manual reference: Section VI.13 Examples: batutil {SEt $z(YYYY)=WW} Internal parameters: HACKER See also: HACKER, $Z ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 121 Documentation for BATUTIL, Version 4.0 $¿ in SEt command Input: US, BU Output: EN Parameters: None In the midst of a SEt string, $Q and $? pause to get a string input from the user and that string then replaces the $¿. Unlike $Q and $? the input is not echoed to the screen(passwode mode). Set colors with the AT/MN commands. No special prompt is put in. Manual reference: Section V.5 Examples: batutil {EC What is your password?$_}{SE name=$¿} Internal parameters: ?Length, ?Size See also: ?Length, ?Size, QUery, AT, MN, $N, $Q ---------------------------------------------------------------------- $<letter> in diverse cmds Input: SY Output: EN, DI Parameters: $ followed by $,t,p,d,v,n,g,l,b,q,h,e,_,P,T,M,D,Y, W,E,J,H,m,S,^,(,),`,' In various places (ECho, PRetty, MEnu, SEt) $<letter> is translated according to DOS prompt metastring rules, SEND/STACKEY extensions and some special BATUTIL extensions. See the list in Section III.2. Manual reference: Section III.2 Examples: batutil {EC Today is $E} Internal parameters: $Translate See also: ECho, FEcho, PRetty, FPretty, MEnu, FMenu, SEt ---------------------------------------------------------------------- $Translate {} Input: CM Output: IN Parameters: none or - {$T -} sets an internal flag turning off translation of $letter metastrings in the set, echo and menu commands. $T undoes the effect of $T -. BATUTIL does not keep internal flags from one running to the next so $ translation is turned back on for each new loading. Manual reference: Section III.2 Examples: batutil {$T-}{EC $E}{$T}{EC $Shi $E} would echo "$E hi July 23, 1988" on July 23, 1988 See also: ^Translate, QUery ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 122 Documentation for BATUTIL, Version 4.0 ++ and -- {} Input: CM Output: IN, EV If the string following ++ or -- is one of the thirty BATUTIL internal variables, $1,...,$0,$é,...,$ò then this is translated to set $1=$V($1+1) or set $1=$V($1-1) Otherwise, if the string after ++ is string, it is translated to set string=$V($x(string)+1) or set string=$V($x(string)-1) Manual reference: Sections V.4, VI.3 Examples: batutil {$1=0}{fordir $2 in () ++ $1}{EC $1} See also: $1=,$V ---------------------------------------------------------------------- > or >> after ECho cmd Input: CM Output: EX Parameters: filename afterwards EC some string> somefile as an INcluded command only will echo that string to the file somefile. If a single > is used, the file is deleted if it already exists unless a ? is placed before the name. In that case, if the file exists a <A>ppend, <O>verwrite, <C>ancel? dialog will popup. If >> is used then append takes place. Manual reference: Section VI.5 Examples: echo $E at $H:$M >> logfile (INcluded commands only) See also: $Wtranslate, STdout ---------------------------------------------------------------------- ? or ! HELP Initial Parameter Output: IN Parameters: Only first two letters count If ? (not in {} or []) is the first parameter on the command line, help is called and the rest of the command line is ignored except that if the first two letters (or first two letters after a { or [) match a command, help for that command is displayed rather than the main help menu. For help to be available, batutil.hlp must be in the default directory or in your path. ! works the same as ? except that ? has some fancy visual effects and ! suppresses them. Manual reference: Section I.3 Examples: batutil ? getkey ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 123 Documentation for BATUTIL, Version 4.0 ?Length {} Input: CM Output: IN Parameters: 1 to 255 (default is 80) Adjusts the maximum length of user input to a $Q or $? in a SEt command Manual reference: Section V.5 Examples: batutil {EC Enter your name}{?L 30}{SEt foo=$Q} See also: ?Size, SEt ---------------------------------------------------------------------- ?Size {} Input: CM Output: IN Parameters: 1 to 80 Adjusts the size of the edit box for the $Q or $? in a SEt command Values: 1 to 80 (default is 50); if ?L is less than ?S, then ?S is adjusted downwards Manual reference: Section V.5 Examples: batutil {EC Enter your name}{?L 30}{?S 20}{SEt foo=$Q} See also: ?Length, SEt ---------------------------------------------------------------------- @Ansi []/{} Input: SY Output: EL Parameters: None Determines if there is an ANSI compatible screen driver present (by saving the current screen and using an ANSI command to move the cursor and checking that the cursor really moved). Values: 0 = No ANSI driver; 1 = ANSI driver found Manual reference: Section II.4 Examples: batutil [@A] ---------------------------------------------------------------------- @Disk []/{} Input: SY Output: EL Parameters: Drive letter; no parameter means default drive Free disk space on the specified or default drive in units of 8K rounded down with 199 returned for 1592K or more free Values: 0 to 199; 239 means invalid drive letter or drive not ready Manual reference: Section II.3 Examples: batutil [@D C] See also: #Disk ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 124 Documentation for BATUTIL, Version 4.0 @Env []/{} Input: SY Output: EL Parameters: None Number of bytes of free environment with 199 returned if there are 199 or more free bytes. This is information about the current ACTIVE DOS environment. Values: 1 to 199 Manual reference: Section II.3 Examples: batutil [@E] See also: #Env ---------------------------------------------------------------------- @Floppy []/{} Input: SY Output: EL Parameters: None For use in systems with a single floppy drive which can be either drive A or B Values: 0 = other than one floppy; 1 = single floppy currently set to drive A; 2= single floppy currently set to drive B Manual reference: Section II.5 Examples: batutil [@F] See also: #Floppy ---------------------------------------------------------------------- @Intel []/{} Input: SY Output: EL Parameters: None Returns information on the type of math coprocessor present Values: 0 = no '87 chip, 1 = 8087, 2 = 287, 3 = 387, 4 = 487 Manual reference: Section II.5 Examples: batutil [@I] See also: #Intel ---------------------------------------------------------------------- @Lim []/{} Input: SY Output: EL Parameters: None Returns the amount of free EMS memory in units of 16K rounded down up to 3184K or more which returns 199 Values: 0 to 199 Manual reference: Section II.3 Examples: batutil [@L] See also: LIm, #Lim, #Mem, #Xtended, @Mem, @Xtended ---------------------------------------------------------------------- @Mem []/{} Input: SY Output: EL Parameters: None Free DOS memory in units of 4K rounded down Values: 0 to 160 Manual reference: Section II.3 Examples: batutil [@M] See also: #Lim, #Mem, #Xtended, @Lim, @Xtended Chapter VIII:COMMAND REFERENCE Page 125 Documentation for BATUTIL, Version 4.0 ---------------------------------------------------------------------- @Prn []/{} Input: SY Output: EL Parameters: printer number from 1 to 3, no parameter defaults to LPT1 Returns information about the status of the printer whose number is given as a parameter Values: returns information about printer as follows: 0 = printer status OK 1 = paper out error 2 = I/O error 3 = Timeout error 4 = invalid printer 5 = other printer error Manual reference: Section II.5 Examples: batutil [@P 2] See also: #Prn ---------------------------------------------------------------------- @Terminal []/{} Input: SY Output: EL Parameters: None Returns the active monitor Values: 0 = monochrome (including Hercules monographics); 1= graphics monitor (CGA, EGA, VGA) Manual reference: Section II.4 Examples: batutil [@T] See also: #Terminal, #Altmon, #Whichmon ---------------------------------------------------------------------- @Xtended []/{} Input: SY Output: EL Parameters: None Returns the amount of free extended memory in units of 16K. Since there is no standard for extended memory, BATUTIL may think that some memory which is used by an application is actually free. It takes into account any VDISK compatible usage. Values: 0 to 199 Manual reference: Section II.3 Examples: batutil [@X] See also: #Lim, #Mem, #Xtended, @Lim, @Mem ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 126 Documentation for BATUTIL, Version 4.0 ^Translate {} Input: CM Output: IN Parameters: None or - {^T -} sets an internal flag turning off translation of ^letter metastrings in the set, echo and menu commands. ^T undoes the effect of ^T -. BATUTIL does not keep internal flags from one running to the next so ^ translation is turned back on for each new loading. Manual reference: Section III.2 Examples: batutil {^T -}{EC ^A}{^T}{EC ^A} would echo the letters ^A and then happy face (= Ctrl-A) See also: $Translate, QUery ---------------------------------------------------------------------- ADdpath []/{} Input: CM Output: EN,EL Parameters: list of paths separated by spaces; $p or $P processed Adds the indicated paths to the PATH unless they are already in the path statement. $p is replaced by the current path and $P by the current path with a trailing backslash. Values: 0 to 199 - number of directories actually added to the PATH Manual reference: Section V.8 Examples: batutil [AD $p] would add the current directory to the path See also: DElpath, PAthedit, EDitenv ---------------------------------------------------------------------- ASciiread []/{} Input: US Output: EL Parameters: None Waits for a keystroke and reports the ASCII value of the key struck (0 for extended keys like <F1>) Values: 0 to 255 Manual reference: Section IV.6 Examples: batutil [AS] Internal parameters: NFlush (determines whether the keyboard is flushed) See also: SCanread, GEtkey, NFlush ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 127 Documentation for BATUTIL, Version 4.0 ATtribute {} Input: CM Output: IN Parameters: Hex number from 0 to FF with optional leading $; special meaning if the parameter is T followed by a one or two digit number. BATUTIL keeps an internal attribute used when EChoing, for shadows in MEnus, when the CLs command clears the screen,for the $? command. It defaults to $1E (yellow on blue). The {AT xx} changes it. See Section III.3 for a list of attributes. Two special values do not have their default meaning: $55 uses the attribute at the cursor at the time that ECho is called; $66 write with no change in the underlying attributes. {AT Tnm} affects how the time is displayed in a {GEtkey WAit...} command: n from 0-3 (default 3) affects how much time is adjusted and m from 1 to 8, the units used in 1/4 seconds (default is 4; i.e. 1 second). Manual reference: Section III.3, Section IV.5 Examples: batutil {EC hello$S}{AT $4F}{EC there} would echo "hello " in yellow on blue and "there" in white on red See also: MNattribute, ECho, PRetty, CLs, EOline, ROw, COl ---------------------------------------------------------------------- BEcho {} Input: CM, BU Output: DI Parameters: string to be echoed (special handling of leading ~ and trailing ~ or ^) Echoes a string with large (8x8) characters to the screen with metastring translation and an automatic big CR. Colors determined by the AT and MN flags (defaulting to $1E on color and $07 on monochrome). A final ^ on the string suppress the big CR. Dot patterns for letters replaced by space for off dots and ASCII 219 for on. This can be changed by the BIgchar command. See that description for the treatment of leading/trailing ~'s. Manual reference: Section III.6 Examples: batutil {BE hi there!} Internal parameters: AT, MN, BI, $T, ^T See also: ECho, PRetty, BPretty, ATttribute, MNattribute, BIgchar ---------------------------------------------------------------------- BEGIN BUSIC keyword Used as the start of a multiple command clause in IF...THEN, IF...THEN...ELSE, FOR, FORDIR and WHILE commands Manual reference: Sections VI.8, VI.9, VI.10 Examples: FORDIR $1 IN () DO BEGIN [] ++ $2 [] EC $2:$1$_ [] END See also: IF, THEN, ELSE, END, FOR, FORDIR, WHILE ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 128 Documentation for BATUTIL, Version 4.0 BIgchar {} Input: CM Output: IN Parameters: one or two ASCII characters. Each character can be replaced by a number from 01 to 255 (use leading 0 for numbers below 10) or a hex number preceded by a $. BEcho and BPretty display large letters based on the dot patterns stored in ROM. On dots are replaced by an "on character" and off dots by an "off character" which default to ASCII 219 (solid block) and ASCII 32 (space). BIgchar allows you to change that - the first parameter is the on character and the second the off character. If the on character is ASCII 255, then the on character displayed is the same as the character being displayed. By default for BEcho, the background character is different from space is displayed on the entire line; leading and trailing ~'s will suppress that. Manual reference: Section III.6 Examples: batutil {BI $20 01}{BP @1FH@1Ei} See also: BEcho, BPretty ---------------------------------------------------------------------- BOx {} Input: CM, BU Output: DI Parameters: top bottom left right [frame movecur] Displays a box on the screen. The four required parameters set the corners of box. The color used is that set by the AT (MN command) with the foreground color used for the frame. By default the frame is a single line but this can be changed with the frame parameter to one of five other possibilities. By default, the cursor moves to just inside the frame but using N for the fifth or sixth parameter will not move the cursor. Manual reference: Section III.4 Examples: batutil {SH +}{AT 3B}{$8=}{BO 8 13 24 52 2} Internal parameters: SH, $8, AT, MN See also: ECho ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 129 Documentation for BATUTIL, Version 4.0 BPretty {} Input: CM, BU Output: DI Parameters: string to be echoed with embedded @ commands (special handling of trailing ~) Echoes a string with large (8x8) characters to the screen with metastring translation and an automatic big CR. Colors determined by the AT and MN flags (defaulting to $1E on color and $07 on monochrome). A final ^ on the string suppress the big CR. Dot patterns for letters replaced by space for off dots and ASCII 219 for on. This can be changed by the BIgchar command. Colors can be changed by @'s in the string to be printed; see the PRetty command. Manual reference: Section III.6 Examples: batutil {BP @1FH@1Ei} Internal parameters: AT, MN, BI, $T, ^T See also: ECho, PRetty, BEcho, ATttribute, MNattribute, BIgchar ---------------------------------------------------------------------- CALL BUSIC command Parameters: labelname Calls a subroutine. Transfers control to the command following the specified labelname until a RET command is encountered at which point control returns to the command following the initial CALL. Labelnames have metastring translation done. Manual reference: Section VI.7 Examples: GO foo1 [] LA foo [] --$1 [] ECho $1$_ [] RET LA foo1 [] FOR $2=1 TO 7 CALL foo See also: GOto, LAbel, RET ---------------------------------------------------------------------- CArousel []/{} Input: SY Output: EL Parameters: None CArousel is special to Softlogic's SOFTWARE CAROUSEL. It returns 0 is CArousel isn't loaded and otherwise returns the current partition number from 1 to 10 (1 to 12 with Carousel 3.0) Values: 0 to 12 Manual reference: Section II.2 Examples: batutil [CA] ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 130 Documentation for BATUTIL, Version 4.0 CASE BUSIC command Multiple choice branch with syntax CASE string OF choice1: cmd11 cmd12 choice2: cmd22 ..... ENDCASE Manual reference: Section VI.8 Examples: CASE $1 OF [] 1:$2=EGA [] 2:$2=VGA [] ENDCASE See also: IF, ENDCASE ---------------------------------------------------------------------- CHeck []/{} Input: CM, SY Output: EL Parameters: Path with or without trailing backslash Determines whether a given path is present in the system Values: 0 = path valid; 9 = path not found Manual reference: Section II.6 Examples: batutil {CH C:\bin} See also: EXist ---------------------------------------------------------------------- CLs {} Input: BU Output: DI Parameters: None Clears the screen in the current internal attributes which are $1E (yellow on blue) by default on a graphics screen and $07 (normal) on a monochrome screen; may be changed with the AT and MN commands Manual reference: Section III.3 Examples: batutil {AT $1F}{CL} would clear the screen in white on red (!) See also: ATtribute, MNattribute, EOline ---------------------------------------------------------------------- COl {} Input: CM Output: DI Parameters: One decimal number with optional +, - or T in front; decimal number must be between 1 and 80. Moves the cursor; if just a number is given the cursor is moved to precisely that column. If a plus or minus precedes the number, then the movement is relative to the current position but wrapping does not take place so that, for example {CO +80} will always go to column 80. {CO Txx} sets the location of where the countdown clock will occur with {GEtkey WAit}. Manual reference: Sections III.8, IV.5 Examples: batutil {CO 5}{EC This line is indented} batutil {RO 1}{EC Time Left:}{RO T1}{CO T12}{GE WA60} See also: ROw, CUrsor ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 131 Documentation for BATUTIL, Version 4.0 CSent {} Input: None Output: IN Parameters: None Input for GEtkey, PMatch and USername are not case sensitive by default; CSent will tell the next call to either of these to be case sensitive. The internal flag is reset by such a call. Manual reference: Section IV.5 Examples: batutil {CS}{GE Y N}{GE Y N} ; the first call would require Y or N; the second would accept Y,y,N or n See also: GEtkey, PMatch, USername ---------------------------------------------------------------------- CUrsor {} Input: CM Output: DI Parameters: + or - required Turns off the Cursor if a minus is used; turns it back on if a + is used. In either case, the cursor is turned back on when BATUTIL exits. Manual reference: Section III.8 Examples: batutil {CU}{EC hit any key}{AS} See also: ROw, COl ---------------------------------------------------------------------- DAte []/{} Input: None Output: EL Parameters: None Returns the day of the month from 1 to 31 Values: 1 to 31 Manual reference: Section II.2 Examples: batutil [DA] See also: HOur, MInute, WEekday, MOnth, YEar ---------------------------------------------------------------------- DElpath []/{} Input: CM Output: EN, EL Parameters: list of paths separated by spaces; $p or $P processed Deletes the indicated paths from the PATH if they are in the path statement. $p is replaced by the current path and $P by the current path with a trailing backslash. Values: 0 to 199 - number of directories actually removed from the PATH Manual reference: Section V.8 Examples: batutil [DE $p] would remove the current directory from the path See also: ADdpath, PAthedit, EDitenv ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 132 Documentation for BATUTIL, Version 4.0 DO BUSIC keyword Required keyword in WHILE loop, optional keyword in FOR loops. Manual reference: Section VI.9 Examples: WHILE $1 < 8 DO BEGIN [] ECHOLN $1 [] ++ $1 [] END FOR $1=1 TO 7 DO ECHOLN $1 See also: WHILE, FOR, FORDIR, UNTIL ---------------------------------------------------------------------- DOs []/{} Input: None Output: EL Parameters: None, 4, N, S, F, B, L, W Returns the DOS Version times ten rounded downwards. "DOS 4" returns 1 if 4DOS is loaded in memory and 0 if not "DOS N" returns 1 if NDOS is loaded in memory and 0 if not "DOS S" returns 1 if share is loaded in memory and 0 if not "DOS B/F/L" return the number of buffers/files handles/maximum logical drives "DOS W" returns 0 if Windows is not loaded, 1 if running in DOS box of Windows in standard or real mode, 2 in a DOS box of Windows/386 2.x and 3 in Windows 3.x in enhanced mode Values: 20,21,30,31,32,33,40 (should work on later versions) 0,1 for "DOS 4/N/S" 0,.. for "DOS B/F/L" 0,1,2,3 for "DOS W" Manual reference: Section II.3 Examples: batutil [DO] ---------------------------------------------------------------------- DRive []/{} Input: None Output: EL Parameters: None DRive returns the current drive with 0=A, 1=B, ...., 25=Z. This is the drive as DOS reports it so if SUBST is in effect, the subst letter will be used. Values: 0 to 25 Manual reference: Section II.3 Examples: batutil [DR] See also: #Disk, @Disk ---------------------------------------------------------------------- DView []/{} Input: SY Output: EL Parameters: None Dview is special to Quarterdeck's DESQVIEW multitasking software. It returns 0 is DesqView isn't loaded and otherwise returns the current partition number from 1 to 199. Values: 0 to 199 Manual reference: Section II.2 Examples: batutil [DV] ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 133 Documentation for BATUTIL, Version 4.0 E European Date Mode Initial Parameter Output: IN Parameters: None If the first parameter on the command line or in BU@ is E (or e), then European dates are turned on for $E and $d and for parameter parsing for $J(...), etc. In $J(2/1/92), by default, the date is February 1, 1992 but when E is turned on, it is January 2. Manual reference: Section I.3 Examples: batutil E {EC $d} ---------------------------------------------------------------------- ECho {} Input: CM, BU Output: DI Parameters: string to be echoed Echoes a string to the screen with metastring translation but no automatic CR/LF. Colors determined by the AT and MN flags (defaulting to $1E on color and $07 on monochrome). Can echo to STDOUT if the STdout command is used. PRetty gives more color control. Manual reference: Section III.3 Examples: batutil {EC hi there!} Internal parameters: AT, MN, ST, $T, ^T See also: FEcho, PRetty, FPretty, ATttribute, MNattribute, STdout,BEcho, ECHOLN, BOx ---------------------------------------------------------------------- ECHOLN {} Input: CM, BU Output: DI Parameters: string to be echoed Echoes a string with trailing CR/LF. Internally echoln .... is translated to echo ....$_ This command does NOT have a minimal truncation. Manual reference: Section III.3 Examples: batutil {ECHOLN hi there!} Internal parameters: AT, MN, ST, $T, ^T See also: FEcho, PRetty, FPretty, ATttribute, MNattribute, STdout,BEcho, ECho ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 134 Documentation for BATUTIL, Version 4.0 EDitenv {} Input: CM, SY, US Output: EN Parameters: Optional Environment variable With no parameter, this command calls up a full screen listing of all variables in the environment with directions on how to edit them. If a single word is given as a parameter, you can edit the string with that value if there is one or you can enter the value of a new variable. Lengths are limited to 255 bytes (rather than DOS' 127). Manual reference: Section V.10 Examples: batutil {ED prompt} Internal parameters: NBeep See also: SEt, PAthedit, NBeep ---------------------------------------------------------------------- ELSE BUSIC keyword Keyword used as part of an IF...THEN...ELSE construction Manual reference: Section VI.8 Examples: IF $1=3 THEN GOto case3 ELSE CALL case2 See also: IF, THEN, BEGIN, END, CASE ---------------------------------------------------------------------- END BUSIC keyword Keyword paired with BEGIN in IF...THEN, IF...THEN...ELSE, FOR, FORDIR and WHILE Manual reference: Sections VI.8, VI.9, VI.10 Examples: FORDIR $1 IN () DO BEGIN [] ++ $2 [] EC $2:$1$_ [] END See also: IF, THEN, ELSE, BEGIN, FOR, FORDIR, WHILE ---------------------------------------------------------------------- ENDCASE BUSIC keyword Keyword paired with CASE Manual reference: Section VI.8 Examples: CASE $1 OF [] 1:$2=EGA [] 2:$2=VGA [] ENDCASE See also: IF, CASE ---------------------------------------------------------------------- ENvrep {} Input: SY Output: DI Parameters: None Gives a report on the screen of the total size and free space of the environment, its location in memory and a listing of all strings with their lengths Manual reference: Section V.2 Examples: batutil {EN} ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 135 Documentation for BATUTIL, Version 4.0 EOline {} Input: CM Output: DI Parameters: None or + {EO} erases to the end of the line in the current attributes as set with AT or MN; {EO +} erase the entire line. {EO} does not change the cursor position; {EO +} moves the cursor to column 1. Manual reference: Section III.3 Examples: batutil {RO -5}{EO +}{CO 5}{EC hi} Internal parameters: AT, MN See also: ATtribute, MNattribute, CLs ---------------------------------------------------------------------- ERrorlevel []/{} Input: CM Output: EL Parameters: Decimal number or Hex number preceded by $$ or $x(environmental variable) This allows the setting of errorlevel to a given number. Values: 0 to 199 Manual reference: Section II.9 Examples: batutil {EC Yes or No?}{GE Y N}{EC $_Thanks!}{ER $(RC)} See also: RUn ---------------------------------------------------------------------- EXist []/{} Input: CM,SY Output: EL, EN Parameters: A single filename without wildcards A powerful extension of DOS' "if exist". If filename has no path or drive, the possible responses are 0 = file exists in default directory; 1 = file exists on path (directory will be given in FDIR; see FDIR below); 2 = file doesn't exist on path. If the filename has a drive or path responses are 0 = file exists; 2 = file does not exist; 9 = path invalid. Possible errors in 23x range - see chapter IX. If the 'file' is a device then FDIR is set to IS_A_DEVICE. Values: 0,1,2,9 Manual reference: Section II.6 Examples: batutil {EX autoexec.bat} Internal parameters: FDIR See also: FDir, CHeck, NUmberfiles, MAke, TOdayfile ---------------------------------------------------------------------- FCommand {} Input: CM, FI Output: IN Parameters: filename and optional label {FC filename label} finds the file "filename" and searches for a line ":label". It then adds to the list of commands to process all lines from the one after that label until the next line starting with ":". Manual reference: Section I.5 Examples: batutil {FC %0 foo} Internal parameters: %0 See also: INclude Chapter VIII:COMMAND REFERENCE Page 136 Documentation for BATUTIL, Version 4.0 ---------------------------------------------------------------------- FDir {} Input: CM Output: IN Parameters: Variable name with leading \ treated specially By default if {EX ...} finds a file in the path but not in the default directory, then the directory of the file is stored in the environmental variable FDIR. Similarly, a choice made by the user in a $f will place the path in the environmental variable FDIR. {FD} with no parameter will suppress and {FD varname} will place it in the variable varname. If varname starts with \ a trailing backspace is added to the path. Manual reference: Section II.6 Examples: batutil {FD \PATH}{EX command.com} See also: EXist, $f ---------------------------------------------------------------------- FEcho {} Input: CM, FI Output: DI Parameters: filename and optional label {FE filename label} finds the file "filename" and searches for a line ":label". It then echoes each line between that label and the next line starting with ":". Full metastring translation takes place. A CR/LF is echoed for each line in the file except for the last. Manual reference: Sections III.6, I.5 Examples: batutil {FE %0 foo} Internal parameters: AT, MN, $T, ^T, %0 See also: ECho, PRetty, FPretty, ATttribute, MNattribute ---------------------------------------------------------------------- FKey {} Input: None Output: IN Parameters: None When used before a MEnu or FMenu command, if there are 9 or fewer menu items, this command turns on display of F1, F2, etc to the left of the menu list and the function and number keys make choices Manual reference: Section IV.3 Examples: batutil {FK}{FM %0 menulist} See also: MEnu, FMenu ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 137 Documentation for BATUTIL, Version 4.0 FMenu []/{} Input: CM, FI, BU, US Output: EL Parameters: filename and optional label {FM filename label} finds the file "filename" and searches for a line ":label". It then processes each line between that label and the next line starting with ":". The input lines up to one beginning with @ are treated as menu items; lines after a @ are treated as help text. Manual reference: Sections IV.2, I.5 Examples: batutil [FM %0 menulist] Internal parameters: NMouse, MHeader, POp, SHadow, FKey, %0 See also: MEnu, NMouse, MHeader, POp, SHadow, FKey ---------------------------------------------------------------------- FOR BUSIC command A BUSIC loop with one of two forms FOR $1=1 TO 10 .... FOR $1 IN (list) If the list has file wildcards, a file search is done. Manual reference: Sections VI.9, VI.10 Examples: FOR $1=1 TO 7 DO ECHOLN $1 FOR $1 IN (*.EXE *.COM) DO ECHOLN $1 See also: WHILE, UNTIL, DO, IN, TO, FORDIR ---------------------------------------------------------------------- FORDIR BUSIC command A BUSIC loop where the loop variable takes on as its values all the directories in a branch of a directory tree including the entire tree of a disk or disks. Manual reference: Section VI.10 Examples: FORDIR $1 IN () DO BEGIN [] ++$2 [] ECHOLN $2:$1 [] END See also: FOR, WHILE, UNTIL, DO, IN, TO ---------------------------------------------------------------------- FPretty {} Input: CM, FI Output: DI Parameters: filename and optional label {FP filename label} finds the file "filename" and searches for a line ":label". It then echoes each line between that label and the next line starting with ":". The initial attributes are determined by AT and MN but they can by changed by using @ followed immediately by a hex attribute. Full metastring translation takes place. A CR/LF is echoed for each line in the file except for the last. Attributes reset to AT/MN for each new line. Manual reference: Sections III.6, I.5 Examples: batutil {FP %0 foo} Internal parameters: AT, MN, %0 See also: ECho, FEcho, FPretty, ATttribute, MNattribute ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 138 Documentation for BATUTIL, Version 4.0 GEtkey []/{} Input: CM, US Output: EL Parameters: List of keys as found in Section IV.4. First parameter may be WAnnn or WAEnnn and final one may be BEep or ELse GEtkey waits for a keystroke from the user from a list supplied with the command and returns the number of the choice in the errorlevel. The choice is echoed on the screen. If the final "key" is BEep, the user is beeped for incorrect choices; if it is ELse, an incorrect choice causes an exit. WAit and WAit with Echo will exit after a period with errorlevel set to 0 Values: 0 to 64 Manual reference: Sections IV.4, IV.5 Examples: batutil {GE Y N} Internal parameters: NFlush, CSent, VIsual See also: MEnu, NFlush, CSent, VIsual ---------------------------------------------------------------------- GOto BUSIC command Parameters: labelname Transfer program control to the line following the label with the specified labelname. If the labelname is not found, the label ELSE is searched for. HALTxxx and EXITxxx have special meanings. Labelnames have metastring translation done. Manual reference: Section VI.7 Examples: GO foo1 [] LA foo [] --$1 [] ECho $1$_ [] RET LA foo1 [] FOR $2=1 TO 7 CALL foo See also: LAbel, CALL ---------------------------------------------------------------------- HACKER {} Input: CM Output: IN {HACKER +} will turn on 'hacker mode' in which you can read and write directly to memory or to ports (equivalent to BASIC's peeks, pokes, in and outs). This mode should only be turned on if you know what you are doing when you write to your hardware! This command does NOT have a minimal truncation. Manual reference: Section VI.13 Examples: batutil {HACKER +}{SEt $Z(0:417)=0} See also: $Z, $z ---------------------------------------------------------------------- HImem []/{} Input: None Output: EL Parameters: None Returns 0 if no XMS (Himem) driver is loaded and 1 if one is loaded Values: 0 or 1 Manual reference: Section II.3 Examples: batutil [HI] ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 139 Documentation for BATUTIL, Version 4.0 HOur []/{} Input: None Output: EL Parameters: None Returns the hour of the day in military time from 0 to 23 Values: 0 to 23 Manual reference: Section II.2 Examples: batutil [HO] See also: DAte, MInute, WEekday, MOnth, YEar ---------------------------------------------------------------------- IF BUSIC command Fundemental branching command with if...then and if...then...else variants. The comparison after if can be equality of strings or numeric comparison (=, > or <). AND and OR are not supported in this version but AND can be simulated with nest IFs and ORs with multiple IF's. A not in the form ~(...) is supported for comparisons. The then and optional else clauses can be a single command or multiple commands within a BEGIN/END pair. Manual reference: Section VI.8 Examples: IF $1=3 THEN GOto case3 ELSE CALL case2 See also: THEN, ELSE, BEGIN, END, CASE ---------------------------------------------------------------------- IN BUSIC keyword Keyword required with FOR loops that are of list form. Manual reference: Section VI.10 Examples: FOR $1 IN (*.EXE *.COM) DO ECHOLN $1 See also: FOR, FORDIR, WHILE, UNTIL, DO, TO ---------------------------------------------------------------------- INclude {} Input: CM, FI Output: IN Parameters: filename and optional label INclude is a synonym for FCommand See also: FCommand ---------------------------------------------------------------------- IOerror {} Input: CM Output: IN Parameters: + or - By default, any file error will stop BATUTIL with a fatal error, usually 233 or 245. {IO -} will prevent the fatal error and instead place an error code into the variable $%. {IO +} will turn file error halting back on. This only affects $R(...) and >> file IO errors. Manual reference: Section VI.5 Examples: IO - [] $R(foobar.txt) [] IF $% > 0 THEN GOto fileerror See also: >, >>, $R, $R(...), $% ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 140 Documentation for BATUTIL, Version 4.0 ISnum [] Input: CM Output:EL Parameters: string string min max Determines if a string is a number in the range [min,max]. Possible returned values are 0 = the string is number between min and max (inclusive) 1 = the string is a number greater than max 2 = the string is a number less than min 3 = it is not a number Manual reference: Section VI.3 Examples: batutil {LA start}{$1=$Q}{IS $1}{IF $r >0 GO start} See also: ++, --, $1=, $N ---------------------------------------------------------------------- KIllenv {} Input: CM Output: EN Parameters: List of environment variables Removes all strings from the environment except for COMSPEC and any variables explicitly listed after {KI} Manual reference: Section V.7 Examples: batutil {SA present.env}{KI path} See also: SAvenv, LOadenv ---------------------------------------------------------------------- LAbel BUSIC command Parameters: labelname The command LA name sets up a label as a target for CALL and GOto. The label ELse has special significance. Manual reference: Section VI.7 Examples: GO foo1 [] LA foo [] --$1 [] ECho $1$_ [] RET LA foo1 [] FOR $2=1 TO 7 CALL foo See also: GOto, CALL ---------------------------------------------------------------------- LEngth []/{} Input: CM Output: EL Parameters: string with metastring translation Returns the length of the string given so {LE $x(foo)} would return the length of the environmental variable foo. Values: 0 to 199 Manual reference: Section V.5 Examples: batutil [LE $x(name)] ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 141 Documentation for BATUTIL, Version 4.0 LIm []/{} Input: None Output: EL Parameters: None Returns 0 if no EMS driver is found and otherwise 10 times the LIM Version. Values: Various - most common are 0, 32, 40 Manual reference: Section II.3 Examples: batutil [LI] ---------------------------------------------------------------------- LOadenv {} Input: CM Output: EN Parameters: Filename or Filename /m Finds the file given (looks on path if need be) and if found either replaces the environment with the content of the file or if the /m parameter is included merges it with the environment. No action taken if the file is not appropriate (ASCII with an equal sign on each line and all caps prior to the equal sign). Manual reference: Section V.7 Examples: batutil {LO present.env} See also: KIllenv, SAvenv ---------------------------------------------------------------------- MAke []/{} Input: CM, SY Output: EL Parameters: A pair of filenames Intended for a homebrewed UNIX type MAKE utility this takes two filenames and returns codes as follows: 0 = file2 not found 1 = file2 is strictly older 2 = file1 not found 3 = file1 older or the same age as file2 9 = path not found Values: 0,1,2,3,9 Manual reference: Section II.8 Examples: batutil [MA foobar.pas foobar.exe] See also: EXist, TOdayfile ---------------------------------------------------------------------- MEnu []/{} Input: CM, BU, US Output: EL Parameters: List of choices separated by spaces Makes a menu with choices given by the list of parameters following the ME command. The number of the user's choice is returned in the errorlevel. Capital letters used for speed choices. Manual reference: Sections IV.1, IV.3 Examples: batutil [ME Copy Erase Rename eXit] Internal parameters: NMouse, MHeader, POp, SHadow, FKey See also: FMenu, NMouse, MHeader, POp, SHadow, FKey ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 142 Documentation for BATUTIL, Version 4.0 MHeader {} Input: CM Output: IN Parameters: String Allows you to specify a header to appear at top of a menu prepared with a subsequent MEnu or FMenu command (on the same BATUTIL command line ). Metastring translation is done. Manual reference: Section IV.3 Examples: batutil {MH My menu: $E}[ME Copy Erase Rename eXit] See also: FMenu, MEnu ---------------------------------------------------------------------- MInute []/{} Input: None Output: EL Parameters: None Returns the minute of the hour from 0 to 59 Values: 0 to 59 Manual reference: Section II.2 Examples: batutil [MI] See also: DAte, HOur, WEekday, MOnth, YEar ---------------------------------------------------------------------- MNattribute {} Input: CM Output: IN Parameters: Hex number from 0 to FF with optional leading $ BATUTIL keeps an internal attribute used when EChoing, for shadows in MEnus, when the CLs command clears the screen,for the $? command. Separate attributes are keep for graphics and monochrome screens. It defaults to $07 (normal). The {MN xx} changes it. See Section III.3 for a list of attributes. Two special values do not have their default meaning: $55 uses the attribute at the cursor at the time that ECho is called; $66 write with no change in the underlying attributes. Manual reference: Section III.3 Examples: batutil {EC hello$S}{MN $70}{EC there} would echo "hello " in normal and "there" in reverse video See also: ATtribute, ECho, PRetty, CLs, EOline ---------------------------------------------------------------------- MOnth []/{} Input: None Output: EL Parameters: None Returns the month of the year from 1 to 12 Values: 1 to 12 Manual reference: Section II.2 Examples: batutil [MO] See also: DAte, HOur, WEekday, MInute, YEar ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 143 Documentation for BATUTIL, Version 4.0 NBeep {} Input: None Output: IN Parameters: None Suppresses beeps in the EDitenv and PAthedit commands Manual reference: Section V.9 Examples: batutil {NB}{ED} See also: EDitenv, PAthedit ---------------------------------------------------------------------- NFlush {} Input: None Output: IN Parameters: None The keyboard is flushed before user input is gotten for the GEtkey and USername commands; NFlush will tell the next call to either of these to not flush the keyboard allowing STACKEY input or prior user input. The internal flag is reset by such a call. Manual reference: Section IV.5 Examples: batutil {NF}{GE Y N}{GE Y N} ; the first call would not flush the buffer; the second would. See also: GEtkey, USername ---------------------------------------------------------------------- NMouse {} Input: None Output: IN Parameters: None MEnu and FMenu allow the use of a Microsoft compatible mouse if present. NMouse will suppress the use of a mouse. The internal flag is reset by such a call. Manual reference: Section IV.1 Examples: batutil {NM}[ME Copy Erase Rename eXit] See also: MEnu, FMenu ---------------------------------------------------------------------- NSound {} Input: None Output: IN Parameters: None The sound command will be suppressed if this parameter is set. Only makes sense if used as part of an BU@ environment string. Manual reference: Section III.10 Examples: set BU@={NS} See also: SOund ---------------------------------------------------------------------- NUmberfiles []/{} Input: CM, SY Output: EL Parameters: filespec(s) with path and wildcards allowed. Returns the total number of files found matching one of the given filespecs up to 199 Values: 0 to 199 Manual reference: Section II.6 Examples: batutil {NU C:\bin\*.com C:\bin\*.exe} See also: EXist, CHeck Chapter VIII:COMMAND REFERENCE Page 144 Documentation for BATUTIL, Version 4.0 ---------------------------------------------------------------------- OF BUSIC keyword Keyword required in CASE statement. Manual reference: Section VI.8 Examples: CASE $1 OF [] 1:$2=EGA [] 2:$2=VGA [] ENDCASE See also: IF, ENDCASE ---------------------------------------------------------------------- P Pause mode Initial Parameter Output: IN Parameters: None If the first parameter on the command line or in BU@ is P (or p), then Pause mode is turned on and messages are displayed when BATUTIL exits with an error and processing is halted until you hit a key. Manual reference: Section I.3 Examples: batutil P {EC $A} ---------------------------------------------------------------------- PAthedit {} Input: SY, US Output: EN Parameters: None Calls up an interactive editor to edit the path Manual reference: Section V.9 Examples: batutil {PA} Internal parameters: NBeep See also: EDitenv, NBeep, ADdpath, DElpath ---------------------------------------------------------------------- PMatch []/{} Input: CM Output: EL Parameters: List of words If the words are labelled word0, word1, ... , this command will try to match word0 to word1,.... If there is no match the errorlevel is set to 0; otherwise to number of the first match found. Intended to check batch file parameters. By default not case sensitive. Values: 0 to 64 Manual reference: Section IV.8 Examples: batutil {PM %1 bold compressed underline} Internal parameters: CSent See also: CSent ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 145 Documentation for BATUTIL, Version 4.0 POp {} Input: CM Output: IN Parameters: None or + By default, menus just appear on the screen. {PO} will cause them to appear with a visual explosion and {PO +} with a visual explosion and a popping sound. The visual/sound effects occur also when the menu pops down. The internal flag is reset by such a call. Manual reference: Section IV.3 Examples: batutil {PO +}[FM %0 menulist] See also: MEnu, FMenu ---------------------------------------------------------------------- PRetty {} Input: CM Output: DI Parameters: String to display with embedded @ commands Like ECho, this will display a string but with a change in attribute possible in mid-string by inserting @ followed by the hex attribute number Manual reference: Section III.5 Examples: batutil {PR @1FH@1Ei} Internal parameters: AT, MN See also: ECho, FEcho, FPretty, ATttribute, MNattribute ---------------------------------------------------------------------- PUt {} Input: CM Output: EN Parameters: + or - The command {PUt +} places all the non-empty internal variables saved by BATUTIL and places them into the DOS environment as strings with values $1, etc. {PUt -} looks at the environment and finds any variables of the form $1,...,$0,$é,...,$ò and moves them to internal variables, removing them from the environment at the same time. These commands are intended to allow saving of values from one running of BATUTIL until another. Manual reference: Section VI.1 Examples: batutil {$1=0}{FORDIR $2 IN () DO ++ $1}{PU +} ---------------------------------------------------------------------- Q Quiet mode Initial Parameter Output: IN Parameters: None If the first parameter on the command line or in BU@ is Q (or q), then Quiet mode is turned on and no messages are displayed when BATUTIL exits with an fatal error. Manual reference: Section I.3 Examples: batutil Q {EC $A} ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 146 Documentation for BATUTIL, Version 4.0 QLock []/{} Input: CM, SY Output: EL, SY Parameters: First parameter one of C,N,S,I; second optional +/- Returns errorlevel based on the states of one of CapsLock, Numlock, ScrollLock, Insert mode. Optional turns off (-) or on (+) Values: 0 = off, 1 = on Manual reference: Section IV.9 Examples: batutil [C -] will test Capslock and turn it off ---------------------------------------------------------------------- QUery {} Input: CM Output: IN Parameters: - or + {QU -} sets an internal flag turning off translation of $Q and $? metastrings in the set command. {QU +} undoes the effect of {QU -}. BATUTIL does not keep internal flags from one running to the next so $Q, $? translation is turned back on for each new loading. Manual reference: Section V.5 Examples: batutil {QU-}{SEt foo1=$Q}{QU +}{SEt foo2=$Q} would set foo1 to $Q and foo2 to a user entered string. See also: $Translates, ^Translate, $Q/$? ---------------------------------------------------------------------- RC {} Input: CM Output: IN Parameters: $ or nothing {RC $} tells BATUTIL to stop using the environmental variable RC and instead store what would have been put into RC instead as an internal variable $r. {RC} resets this to return to the use of RC and to having calls to $r be equivalent to $x(rc). Manual reference: Section VI.1 Examples: batutil {RC $}{DOs W}{EC $r} ---------------------------------------------------------------------- REm {} Input: None Output: None Parameters: None Allows placing of remarks in a BATUTIL command line Manual reference: Section I.5 Examples: batutil {AT $4E}{CL}{RE clears screen in red!} ---------------------------------------------------------------------- REPEAT BUSIC command BUSIC command to cycle through a set of commands at least once checking at the end of a cycle to see if a condition holds. If the condition holds then stop the cycle; otherwise repeat it. Manual reference: Section VI.9 Examples: REPEAT [] ECHOLN $1 [] ++ $1 [] UNTIL $1 > 7 See also: UNTIL, WHILE ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 147 Documentation for BATUTIL, Version 4.0 RET BUSIC keyword Parameters: None Matching keyword required at the end of subroutine. It must have a matching LAbel. You need to jump over subroutines because a RET reached not as part of a CALL is an error. Manual reference: Section VI.7 Examples: GO foo1 [] LA foo [] --$1 [] ECho $1$_ [] RET LA foo1 [] FOR $2=1 TO 7 CALL foo See also: GOto, LAbel, CALL ---------------------------------------------------------------------- ROw {} Input: CM Output: DI Parameters: One decimal number with optional +, - or T in front; decimal number must be between 1 and 25. Moves the cursor; if just a number is given the cursor is moved to precisely that row. If a plus or minus precedes the number, then the movement is relative to the current position but wrapping does not take place at the screen top. Scrolling will take place at the screen bottom. {RO Txx} sets the location of where the countdown clock will occur with {GEtkey WAit}. Manual reference: Sections III.8, IV.5 Examples: batutil {CL}{RO 5}{EC This line is line 5} batutil {RO 1}{EC Time Left:}{RO T1}{CO T12}{GE WA60} See also: COl, CUrsor ---------------------------------------------------------------------- RUn []/{} Input: CM Output: EL, EX Parameters: Program name and parameters This will search the path for the program in question, run it and return the errorlevel. Only runs com and exe files but you can use command.com with the C parameter to run batch files or internal commands. By default, BATUTIL will swap most of itself to EMS or disk. Values: 0 to 255 Manual reference: Section II.7 Examples: batutil [RU programname] ---------------------------------------------------------------------- SAvenv {} Input: CM Output: EN Parameters: Filename Saves the current environment to an ASCII file in the form VARNANE=var_value one variable per line. Errorlevel set to 199 if the filename exists and user doesn't allow the file to be overwritten Manual reference: Section V.7 Examples: batutil {SA present.env} See also: KIllenv, LOadenv ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 148 Documentation for BATUTIL, Version 4.0 SCanread []/{} Input: US Output: EL Parameters: None Waits for a keystroke and reports the "Scancode" part of the int 16H value for the keystruck Values: 0 to 199 Manual reference: Section IV.6 Examples: batutil [SC] Internal parameters: NFlush (determines whether the keyboard is flushed) See also: ASciiread, GEtkey, NFlush ---------------------------------------------------------------------- SEt {} Input: CM Output: EN Parameters: One or more of the form varname=varvalue SE allows you to place variables in the active DOS environment. Metastring translation takes place including $x, $f, $Q/$?/$N. Manual reference: Sections V.3, V.4, V.5 Examples: batutil {ec Enter filespec}{set ab=$Q file=$f($x(ab))} Internal parameters: $Translate, ^Translate, QUery See also: $f, $x, $Q/$?, $Translate, ^Translate, QUery ---------------------------------------------------------------------- SHadow {} Input: None Output: IN Parameters: None By default, menus just appear on the screen. {SH} will cause them to appear with shadow in the current colors as set by AT/MN. The internal flag is reset by such a call. Manual reference: Section IV.3 Examples: batutil {SH}[FM %0 menulist] Internal parameters: AT, MN See also: MEnu, FMenu ---------------------------------------------------------------------- SKey {} Input: CM Output: EX Parameters: Stackey command string (with limitations) So long as Stackey is loaded before BATUTIL, the SKey command will place keystrokes in the Stackey buffer without the need to RUn stackey. Most but not all Stackey commands are allowed and metastring translation takes place. Manual reference: Section II.7 Examples: batutil {SK F1 "hi there" $E ^T} See also: RUn ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 149 Documentation for BATUTIL, Version 4.0 SOund {} Input: CM Output: DI Parameters: Sound number from 1 to 20; optional repeat count Makes one of 20 sounds; 1 to 10 are small sounds, 11 to 20 are tunes Manual reference: Section III.10 Examples: batutil {SO 18} Internal parameters: NSound See also: NSound ---------------------------------------------------------------------- STdout {} Input: CM Output: IN Parameters: - or optional + {ST +} (equivalent to {ST}) will direct output from the BATUTIL {ECho} command to standard output which can redirected. {ST -} will return to the default behavior of writing ECho output directly to the screen in colors set with AT/MN. Manual reference: Section III.9 Examples: batutil {ST}{EC ^G}{ST -}{EC You dummy!!!} See also: ECho ---------------------------------------------------------------------- THEN BUSIC keyword Keyword used as part of IF...THEN and IF...THEN...ELSE constructions Manual reference: Section VI.8 Examples: IF $1=3 THEN GOto case3 ELSE CALL case2 See also: IF, ELSE, BEGIN, END, CASE ---------------------------------------------------------------------- TO BUSIC keyword Keyword used as part of a incremental FOR loop Manual reference: Section VI.9 Examples: FOR $1=1 T0 8 ECHOLN $1 See also: FOR, WHILE, UNTIL, DO, IN ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 150 Documentation for BATUTIL, Version 4.0 TOdayfile []/{} Input: CM, SY Output: EL Parameters: Filename without wildcards; optional hour {TO filename} will search for the file specified and check its date against today's date and return the following: 0 = the file has today's date 1 = the file exists and doesn't have today's date 2 = file not found 9 = invalid path If two parameters are given, the first must be a number from 0 to 23. Then, "today" and the file date/time will be compared assuming days start at the hour in the first parameter. Values: 0,1,2,9 Manual reference: Section II.8 Examples: batutil {TO test.txt} batutil {TO 5 test.txt} See also: EXist, MAke ---------------------------------------------------------------------- TRace {} IN: CM, BU, US OUT: DI, IN, EX Parameters: Ffilename, Wvarname, W-, ON, OFF, *, %, nnn, $nn, Xnnn,X$nn {TR on} will turn on BATUTIL's interactive debugger. There are many other options including output to a file, watch variables and more. See the detailed discussion in the manual. Manual reference: Section VI.12 Examples: batutil {TR ON} ---------------------------------------------------------------------- UNTIL BUSIC keyword Keyword that matches REPEAT and indicates the end of a repeat cycle. The condition that is checked at the end of the cycle appears on the UNTIL line. Manual reference: Section VI.9 Examples: REPEAT [] ECHOLN $1 [] ++ $1 [] UNTIL $1 > 7 See also: REPEAT, WHILE ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 151 Documentation for BATUTIL, Version 4.0 USername []/{} Input: CM, US Output: EL Parameters: sequence of names; first one can be a number of tries; second can be * In its simplest form, a sequence of words are given following {US. The user types in a "username" and BATUTIL responds which number in the list was matched and 0 if the string did not match. If a number is given as the first parameter, the user will have additional chances and the remaining parameters are labeled 1,2,.. and the same rules apply. If the second parameter is *, the same rules apply (with the third parameter now as choice 1) BUT the system is halted if no correct choice is given. Values: 0 to 64 Manual reference: Section IV.7 Examples: batutil [US george mary scott] Internal parameters: CSent See also: CSent ---------------------------------------------------------------------- V Verbose mode Initial Parameter Output: IN Parameters: None If the first parameter on the command line or in BU@ is V (or v), then Verbose mode is turned on and messages are displayed when BATUTIL exits with an error. Manual reference: Section I.3 Examples: batutil V {EC $A} ---------------------------------------------------------------------- VIsual {} Input: CM Output: IN Parameters: A,1,N,D,DA,D1,DN Determines the degree of visual feedback from the GEtkey command. The default is to have matching choices echoed including #nnn and two letter abbreviations. A will have incorrect choices echoed in the form letter? or ¿? for keys without ASCII codes. 1 will restrict echoes only to single ASCII codes and N will suppress echos. By default, the cursor moves on space after a GEtkey - D suppresses that space. Manual reference: Section IV.5 Examples: batutil {VI DA}{EC Choose a key}{GE Y N} See also: GEtkey ---------------------------------------------------------------------- WEekday []/{} Input: None Output: EL Parameters: None Returns the day of the week from 0 = Sunday to 6 = Saturday Values: 0 to 6 Manual reference: Section II.2 Examples: batutil [WE] See also: DAte, HOur, MOnth, MInute, YEar Chapter VIII:COMMAND REFERENCE Page 152 Documentation for BATUTIL, Version 4.0 ---------------------------------------------------------------------- WHILE BUSIC command A BUSIC loop command. A condition is checked before the loop begins and if it fails the loop is terminated. Multiple commands allow with a BEGIN...END pair. Manual reference: Section VI.9 Examples: WHILE $1 < 8 DO BEGIN [] ECHOLN $1 [] ++ $1 [] END See also: DO, UNTIL ---------------------------------------------------------------------- Year []/{} Input: None Output: EL Parameters: None Returns the year since 1980 (i.e. 0 = 1980, 10 = 1990) Values: 0 to 19 Manual reference: Section II.2 Examples: batutil [YE] See also: DAte, HOur, WEekday, MInute, MOnth ---------------------------------------------------------------------- Chapter VIII:COMMAND REFERENCE Page 153 Chapter IX:ERROR MESSAGES IX.1 Fatal Errors There are certain errors that you may make in syntax or problems with your trying to place something in the environment for which there isn't room from which BATUTIL cannot recover or where it cannot figure out the action you'd want it to take. There may also be situations where what we think is the environment doesn't seem right and BATUTIL would then want you to contact us and inform us of what has happened. In all these situations BATUTIL exits. One action it does to indicate such a fatal error is to exit with the DOS errorlevel set to a number between 200 and 253. Only the AScii command and the RUn command can return errorlevels in this range without indicating an error. Errorlevel 254 is reserved for the HAltif command and errorlevel 255 for ^Break exits. All other commands set an errorlevel in the range 0 to 199. BATUTIL was incompatible with early versions of DR DOS 5.0 and with later versions of the same product if run from a shell and would give fatal error messages. This problem persists with DR DOS 6.0. It's because of a lack of DOS compatibility. It will run if 4DOS is used over DRDOS rather than DRDOS' command.com. While debugging a BATUTIL script, you can use either VERBOSE or PAUSE mode. The verbose mode is the default and can be turned off by using a Q (not in brackets) as the first non blank character on the BATUTIL command line or in the BU@ environmental variable. Pause mode can be turned on similarly except that P is used in place of V. See Section I.3 for further discussion. Normally, file errors are fatal but you can modify this behavior for $R errors with the IO command, see Section VI.5. IX.2 List of Error Codes 200: Not a BATUTIL command 201: Does not effect errorlevel; use {} not [ ] 202: Incorrect placement of [,],{ or } 204: Some of the required parameters are missing 205: Too many parameters 206: Number expected 207: Number out of allowed range 208: Illegal value for parameter 209: Metastring syntax error 211: Unable to locate DOS environment Chapter IX:ERROR MESSAGES Page 154 Documentation for BATUTIL, Version 4.0 212: Environment corrupted or not found 213: Internal error in environment handling 215: Too many variables in environment 216: Environmental variable too large 217: Environment too small for attempted change 218: Error communicating with STACKEY 220: SAVENV error: path not found 221: SAVENV/LOADENV error: file access error 222: LOADENV error: file not found 223: LOADENV error: invalid environment in file 224: LOADENV error: Too large environment in file 225: WHILE, CASE or FOR syntax error 226: Invalid path variable in environment 227: Proposed new path is too long 228: No matching THEN, RET, UNTIL, END or ENDCASE 229: Unmatched RET, END, ENDCASE or UNTIL 230: Drive not ready 231: Other DOS disk error 232: DOS unable to access drive {DRIVE LETTER} 233: File error with $R read 234: File or other error on writing to a file 235: RUN error: Program not found 236: RUN error: Insufficient memory to run program 237: RUN error: DOS error 238: RUN error: Swap file open error or bad path 239: LABEL not found in GOTO or CALL command 240: FECHO, FPRETTY, FMENU, FCOMMAND error: file not found 241: FECHO, FPRETTY, FMENU, FCOMMAND error: label not found 242: FECHO, FPRETTY, FMENU error: too many lines between labels 243: FECHO, FPRETTY, FMENU, FCOMMAND error: no lines between labels 245: Too many items in MENU or FMENU 246: Improper FMENU lines 247: Trace command syntax error 248: Command stack overflow (limit of 1024 commands) 249: Insufficient memory for requested operation 250: Comparison error: No comparison given 253: Turbo Pascal Runtime Error! IX.3 Explanation of Error Codes 200: Not a BATUTIL command The first word inside each pair of {} or [] must be one of the BATUTIL commands or must be a valid truncation (have at least Chapter IX:ERROR MESSAGES Page 155 Documentation for BATUTIL, Version 4.0 the first two letters and the remaining letters agree with a BATUTIL command). ========================================================================== 201: Does not effect errorlevel; use {} not [ ] Some BATUTIL commands set the errorlevel and may be placed inside [] (see Section I.4). You placed a command NOT of this type inside []. ========================================================================== 202: Incorrect placement of [,],{ or } BATUTIL was unable to parse the command line because of extra or missing brackets. Here are some examples where you will get this error: batutil {} batutil {EC hi batutil {EC hi{ ========================================================================== 204: Some of the required parameters are missing The command requires more parameters than you have given or you may have given no parameters. ========================================================================== 205: Too many parameters BATUTIL has found more parameters than it expected. If you place a parameter with a space in it, you will often get this error since BATUTIL parses a space as a separator between parameters. To place a space in most parameters, use $S. ========================================================================== 206: Number expected There are certain place where BATUTIL expects a number, e.g. in {AT xx} where xx should be a number. If there is not a number there, then you'll get this message, for example if you type batutil {AT HI} ========================================================================== 207: Number out of allowed range In a command like {CO xx}, the parameter x must lie in the range 1 to 80 (unless proceeded by a + or -). At least this is so if the screen is 80 columns wide. You'll get this error if a number out of the allowed range is provided. ========================================================================== 208: Illegal value for parameter BATUTIL uses this to indicate some other error in the form of a parameter, e.g. {CU x} must have x equal to + or - and you'll get this error if you use another value. In some places, you'll get this error when error 205 might be more appropriate. ========================================================================== Chapter IX:ERROR MESSAGES Page 156 Documentation for BATUTIL, Version 4.0 209: Metastring syntax error BATUTIL found an error when trying to do metastring translation. This most often happens when a $ or a ^ is followed by an illegal character. To place an actual $ or ^ in a string (which can then be followed by anything) remember to use $$ or $^. In addition, this error can occur when there is a syntax error with the $V or $s command. for example, here are possible suberrors with the $V command: illegal character parenthesis mismatch spacing error operator missing next to parenthesis number too large negative powers illegal divide by zero ========================================================================== 211: Unable to locate DOS environment Please report this error to CTRLALT Associates. Since BATUTIL will manipulate the true DOS environment, it is essential that it be found. We believe that our method using undocumented information will always work but if BATUTIL cannot find what it is sure is the real environment, it will exit. See the discussion of DRDOS above. ========================================================================== 212: Environment corrupted or not found Please report this error to CTRLALT Associates. Since BATUTIL will manipulate the true DOS environment, it is essential that it be found. We believe that our method using undocumented information will always work but if BATUTIL cannot find what it is sure is the real environment, it will exit. This message indicates that BATUTIL found what it believes to be the DOS environment and it didn't have the proper form. Either BATUTIL didn't find the true environment or your true environment is corrupted. IMPORTANT NOTE: If you are using 4DOS and get this error, only report it if you loaded 4DOS with the /M:xxx parameter. BATUTIL is incompatible with versions of 4DOS prior to 2.1 or ones not loaded with /M. ========================================================================== 213: Internal error in environment handling Please report this error to CTRLALT Associates. Since BATUTIL will manipulate the true DOS environment, it is essential that it be found. We believe that our method using undocumented information will always work but if BATUTIL cannot find what it is sure is the real environment, it will exit. ========================================================================== Chapter IX:ERROR MESSAGES Page 157 Documentation for BATUTIL, Version 4.0 215: Too many variables in environment BATUTIL cannot handle environments with more than 510 different strings in it. If you have more than that many strings, let us know - we're curious what you could possibly have there! ========================================================================== 216: Environmental variable too large BATUTIL cannot handle environments where any string has more than 255 characters. Normally, you shouldn't have any such strings since DOS only allows strings up to 127 characters and BATUTIL only up to 255. Let us know if you'd like this limit of 255 increased. ========================================================================== 217: Environment too small for attempted change You tried, e.g. with a {SE } command to place something in the environment for which there was insufficient room. ========================================================================== 218: Error communicating with STACKEY This will happen in three different contexts: - you try the SKEY command and STACKEY is not resident - the STACKEY buffer would overflow if your request is processed - you made a syntax error in what you placed after the SKey command In either of the later cases, the STACKEY buffer will be flushed. ========================================================================== 220: SAVENV error: path not found The directory part of the filespec in {SA filespec} was invalid. ========================================================================== 221: SAVENV/LOADENV error: file access error There was a disk or other error that prevented access to the file in question. The most common cause of this will be a disk full or write protected disk during a SAVENV. The error message displayed on the screen will give extra information (ignore the extra error number given). ========================================================================== 222: LOADENV error: file not found The file which you asked to have loaded into the environment could not be found. ========================================================================== 223: LOADENV error: invalid environment in file There was a line in the file you asked to have loaded into the environment or it did not have the form INCAPS=string Chapter IX:ERROR MESSAGES Page 158 Documentation for BATUTIL, Version 4.0 on each line. A file obtained with {SAvenv} should always load without this message. If you get this message with a file saved with BATUTIL, please notify CTRLALT Associates. ========================================================================== 224: LOADENV error: Too large environment in file No room in the DOS environment for the file you tried to load. ========================================================================== 225: WHILE, CASE or FOR syntax error This can happen in the following places: - you try to nest CASE statements - your file/fordir/explicit list has more than 500 items - you used FOR..IN without (..) after the IN - you used an illegal loop variable with FOR $?= - you didn't follow FOR $? with IN or = - with FOR $?= start TO stop, start or stop was invalid - the required TO was left out of FOR $?=... - the required DO was left off a WHILE statement ========================================================================== 226: Invalid path variable in environment In parsing the path for a {DElpath ...} or {ADdpath ...} command, BATUTIL found an invalid path. Valid paths have strings without spaces separated by semicolons with an optional semicolon at the end. DOS will accept invalid path strings with its PATH command. ========================================================================== 227: Proposed new path is too long BATUTIL limits environmental strings to 255 bytes each. Your attempt to use {ADdpath ...} or {PAthedit} would have resulting in path in excess of 255 characters and so it was not accomplished. Let us know if you'd like to have paths over 255 characters. ========================================================================== 228: No matching THEN, RET, UNTIL, END or ENDCASE You had an unmatched multicommand start without a closing stop normally one of IF but no THEN a CALL with no RET REPEAT but no UNTIL BEGIN but no END CASE but no ENDCASE ========================================================================== 229: Unmatched RET, END, ENDCASE or UNTIL You had an unmatched multicommand stop without a start normally one of RET without a matching LAbel or not in a CALL Chapter IX:ERROR MESSAGES Page 159 Documentation for BATUTIL, Version 4.0 END without a BEGIN ENDCASE without a CASE UNTIL without a REPEAT Note that you cannot use a label for both a CALL and GOTO because of the matching RET requirement. ========================================================================== 230: Drive not ready DOS error - usually due to an open diskette drive door. ========================================================================== 231: Other DOS disk error DOS wouldn't allow access to the file and reported an error other than Drive not ready. ========================================================================== 232: DOS unable to access drive {DRIVE LETTER} Used by the #Disk and @Disk commands to indicate either error 230 or 231. ========================================================================== 233: File error with $R read Either you failed to specify a file to read from (!) or there was a DOS file error. ========================================================================== 234: File or other error on writing to a file Either you failed to specify a file to write to (!) or there was a DOS file error. ========================================================================== 235: RUN error: Program not found The program name after a {RUn ...} command wasn't in the current directory or on the path (or in the directory name that you gave). RUn can only run EXE and COM programs and not batch files or internal commands. To run batch files or internal commands use command /c as in {RUN command /ccopy $1 $2} ========================================================================== 236: RUN error: Insufficient memory to run program DOS reported insufficient free memory to run the program you asked to RUn. ========================================================================== 237: RUN error: DOS error DOS reported an error when trying to run the program that you asked to RUn. All these errors are unusual and you should report any such message to CTRLALT Associates together with the extra "special error number" which was reported. ========================================================================== 238: RUN error: Swap file open error or bad path Chapter IX:ERROR MESSAGES Page 160 Documentation for BATUTIL, Version 4.0 Either you specified an invalid path in BUSWAP or there was a DOS file error in trying to access the swapfile in a RUN with swap. ========================================================================== 239: LABEL not found in GOTO or CALL command The label specified in a GOTO or CALL was not found AND an ELSE label wasn't found either. ========================================================================== 240: FECHO, FPRETTY, FMENU, FCOMMAND error: file not found In {FEcho filename label}, the file filename could not be found or similarly for FPretty, FMenu or FCommand. ========================================================================== 241: FECHO, FPRETTY, FMENU, FCOMMAND error: label not found In {FEcho filename label}, the label could not be found or similarly for FPretty, FMenu or FCommand. ========================================================================== 242: FECHO, FPRETTY, FMENU error: too many lines between labels These commands can only read in 25 lines (which is all you'd normally want!) and will give an error if the end of the file or another label is not reached before 26 lines (exclusive of comments) are read. ========================================================================== 243: FECHO, FPRETTY, FMENU, FCOMMAND error: no lines between labels Either the first line in a file where no label was given or the line following the label give was itself a label line (i.e. began with :). ========================================================================== 245: Too many items in MENU or FMENU Menus are limited to 16 choices. ========================================================================== 246: Improper FMENU lines The first line in FMENU began with an @ which is only used to separate menu items from help text. ========================================================================== 247: Trace command syntax error Invalid parameter used with the TRace command. ========================================================================== 248: Command stack overflow (limit of 1024 commands) You tried to read in more than 1024 commands in a FCommand or else a translation of a CASE or FOR produced a set of commands with more than 1024 commands in it. ========================================================================== 249: Insufficient memory for requested operation BATUTIL had insufficient memory to process a command; normally this will only happen if you have a non-terminating nest due to Chapter IX:ERROR MESSAGES Page 161 Documentation for BATUTIL, Version 4.0 improper code. BATUTIL stores information in a 'heap' which is about 300K less than the amount of free memory when BATUTIL loads. Internal variables are stored there as well as all commands and roughly 6K overhead for each 'command level'. ========================================================================== 250: Comparison error: No comparison given Each HAltif parameter and every comparison associated to an IF, WHILE or REPEAT must have an =, > or < (NOTE: IF YOU USE THE DOS COMMAND LINE THE > OR < MUST BE ENTERED AS $g OR $l TO AVOID A DOS REDIRECTION). ========================================================================== 253: Turbo Pascal Runtime Error! Most errors indicate mistakes you made or system errors but if you get this message, it means that we made an error because we failed to catch an error and the underlying Turbo Pascal code was called into play. Please report the problem to us with the extra information displayed on the screen. =========================================================================== Chapter IX:ERROR MESSAGES Page 162 INDEX #Altmon 30, 113 BIgchar 129 #Comm 32, 113 BIGECHO 47 #Disk 29, 113 BOx 45, 129 #Env 29, 113 BPretty 130 #Floppy 32, 114 buffers, DOS 27 #Game 32, 114 BUSIC 90 #Intel 31, 114 CALL 92, 130 #Keyboard 30, 114 CArousel 28, 130 #Lim 28, 114 CASE statement 96, 131 #Mem 28, 115 CHeck 34, 131 #Prn 31, 115 CLs 45, 131 #Rodent 31, 115 COl 50, 62, 131 #Terminal 29, 115 Control Break 23 #Vmode 30, 115 count, character 83 #Whichmon 30, 116 count, word 83 #Xtended 28, 116 CSent 60, 132 $% 117 CUrsor 17, 51, 132 $L 63 DAte 26, 132 $r 15 date arithmetic 41, 86 $R(con) 119 dates, European 11 $Rtranslate 88, 120 debugging 102, 151 $s 82 DElpath 78, 132 $Translate 39, 122 DOs 27, 133 $V 84 DRDOS 154 $Wtranslate 88, 120 DRive 27, 133 $Z 121 DView 28, 133 $z 121 ECho 43, 134 ++ 84 EDitenv 80, 135 -- 84 ELSE 135 4DOS 9, 27, 69 END 135 ?Length 72, 124 ENDCASE 135 ?Size 72, 124 environment 16, 67 @Ansi 30, 124 environment, loading 76 @Disk 29, 124 environment, saving 76 @Env 29, 125 ENvrep 69, 135 @Floppy 32, 125 EOline 45, 136 @Intel 31, 125 ERrorlevel 14, 38, 136 @Lim 28, 125 European dates 11, 134 @Mem 28, 125 EXist 32, 136 @Prn 31, 126 Fatal Errors 154 @Terminal 30, 126 FCommand 17 @Xtended 28, 126 FDir 33, 137 ^Translate 39, 127 FEcho 17, 137 ADdpath 78, 127 file handles 27 arithmetic 84 file pick list 75 AScii 63 filename parsing 41 ASciiread 127 FKey 56, 137 ATtribute 45, 128 FMenu 17, 56, 138 BEcho 47, 128 FOR 138 BEGIN 128 FOR list 98 FOR statement 96 PIANOMAN 52 FORDIR 98, 138 pick list 75 format 83 PMatch 64, 145 FPretty 17, 138 pokes 105 GEtkey 58, 60, 139 POp 56, 146 GOto 92, 139 PRetty 46, 146 hacker mode 105, 139 PROMPT metastrings 39 help 9 PUt 82, 146 HImem 28, 139 QLock 65, 147 HOur 26, 140 QUery 72, 147 IF...THEN...ELSE 94, 140 Quiet mode 10, 146 INclude 17, 140 RC 82, 147 ins 105 Read from file 88 internal variables 81 registration 4 IOerror 88, 140 REPEAT 97, 147 IS_A_DEVICE. 34 RET 148 ISnum 84, 141 ROw 50, 62, 148 KIllenv 76, 141 RUn 34, 148 LAbel 18, 92, 141 SAvenv 76, 148 laptop 10 saving the environment 76 lastdrive 27 SCanread 63, 149 LEngth 72, 141 SEt 70, 149 LIm 27, 142 SHadow 56, 149 line editor 19 share 27 LOadenv 76, 142 SKey 149 loading the environment76 SOund 52, 150 Lock status 65 STACKEY metastrings 40 lowercase 83 standard output 51 MAkefile 38, 142 STdout 51, 150 MEnu 54, 56, 142 string manipulation menu waits 58 82, 120 MENUDEMO 55 substring 83 menus 106 supermetastring 15 metastrings 39 Supermetastring 116 MHeader 56, 143 syntax 13 Microsoft Windows 27 THEN 150 minimal truncation 14 TO 150 MInute 26 TOdayfile 37, 151 MInute 26, 143 TRace 102, 151 MNattribute 45, 143 UNTIL 151 MOnth 26, 143 uppercase 83 NBeep 79, 144 USername 63, 152 NDOS 27 Verbose mode 10, 152 NFlush 60, 144 VIsual 60, 152 NMouse 54, 144 waits, menu 58 NSound 52, 144 WARNING 68 NUmberfiles 34, 144 watch 104 OF 145 WEekday 26, 152 outs 105 WHATEL 35 OView 28 WHILE statement 97 parsing 41 Windows 27 path control 78 word count 83 PAthedit 79, 145 Write to file 88 Pause mode 10, 145 Year 26, 153 peeks 105